### Start Vane Application (Non-Docker)

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

Start the Vane application after installing dependencies and building. Access Vane at http://localhost:3000 to complete setup.

```bash
npm run start
```

--------------------------------

### Install Vane Dependencies and Build

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

Install project dependencies using npm and build the application for non-Docker installation. Ensure SearXNG is installed and configured with JSON format and Wolfram Alpha enabled.

```bash
npm i
npm run build
```

--------------------------------

### Docker Deployment - Full Image

Source: https://context7.com/itzcrazykns/vane/llms.txt

Deploys Vane using the full Docker image, which includes a bundled SearxNG instance. This is a quick start option for a complete setup.

```bash
# Full image (includes SearxNG)
docker run -d \
  -p 3000:3000 \
  -v vane-data:/home/vane/data \
  --name vane \
  itzcrazykns1337/vane:latest
```

--------------------------------

### Build and Run Vane from Source (Docker)

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

Build the Vane Docker image and run it after cloning the repository. This method provides more control over the setup.

```bash
docker build -t vane .
docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane vane
```

--------------------------------

### Clone Vane Repository

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

Clone the Vane repository to build from source or for advanced setup. Ensure Docker is installed and running before cloning.

```bash
git clone https://github.com/ItzCrazyKns/Vane.git
```

--------------------------------

### UI Chat Endpoint SSE Stream Example

Source: https://context7.com/itzcrazykns/vane/llms.txt

This example shows the Server-Sent Events (SSE) stream format for the chat endpoint. It includes various block types like research, source, and text, with updates for block content.

```json
{"type":"block","block":{"id":"b1","type":"research","data":{"subSteps":[]}}}
{"type":"updateBlock","blockId":"b1","patch":[{"op":"replace","path":"/data/subSteps/0/searching","value":["quantum entanglement"]}]}
{"type":"researchComplete"}
{"type":"block","block":{"id":"b2","type":"source","data":[{"content":"...","metadata":{}}]}}
{"type":"block","block":{"id":"b3","type":"text","data":"Quantum entanglement is..."}}
{"type":"updateBlock","blockId":"b3","patch":[{"op":"replace","path":"/data","value":"Quantum entanglement is a phenomenon..."}]}
{"type":"messageEnd"}
```

--------------------------------

### Docker Deployment - Slim Image

Source: https://context7.com/itzcrazykns/vane/llms.txt

Deploys Vane using the slim Docker image, requiring you to provide your own SearxNG instance via the SEARXNG_API_URL environment variable. Use this if you have a separate SearxNG setup.

```bash
# Slim image (bring your own SearxNG)
docker run -d \
  -p 3000:3000 \
  -e SEARXNG_API_URL=http://your-searxng:8080 \
  -v vane-data:/home/vane/data \
  --name vane \
  itzcrazykns1337/vane:slim-latest
```

--------------------------------

### Run Vane with Docker

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

This command pulls and starts the Vane container with the bundled SearxNG search engine. It maps port 3000 and creates persistent volumes for data and uploaded files. Access Vane at http://localhost:3000 after it's running.

```bash
docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest
```

--------------------------------

### Standard Search Response (JSON)

Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md

This is an example of a standard JSON response when streaming is disabled (stream: false). It contains the search message and a list of sources used.

```json
{
  "message": "Vane is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online. Here are some key features and characteristics of Vane:\n\n- **AI-Powered Technology**: It utilizes advanced machine learning algorithms to not only retrieve information but also to understand the context and intent behind user queries, providing more relevant results [1][5].\n\n- **Open-Source**: Being open-source, Vane offers flexibility and transparency, allowing users to explore its functionalities without the constraints of proprietary software [3][10].",
  "sources": [
    {
      "content": "Vane is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online.",
      "metadata": {
        "title": "What is Vane, and how does it function as an AI-powered search ...",
        "url": "https://askai.glarity.app/search/What-is-Vane--and-how-does-it-function-as-an-AI-powered-search-engine"
      }
    },
    {
      "content": "Vane is an open-source AI-powered search tool that dives deep into the internet to find precise answers.",
      "metadata": {
        "title": "Sahar Mor's Post",
        "url": "https://www.linkedin.com/posts/sahar-mor_a-new-open-source-project-called-vane-activity-7204489745668694016-ncja"
      }
    }
        ....
  ]
}
```

--------------------------------

### Conversation History Example

Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md

Provide conversation history as an array of [role, message] pairs to maintain context for the search query.

```json
[
  ["human", "What is Vane?"],
  ["assistant", "Vane is an AI-powered search engine..."]
]
```

--------------------------------

### Update Vane (Non-Docker)

Source: https://github.com/itzcrazykns/vane/blob/master/docs/installation/UPDATING.md

Update Vane from source without Docker. Pull latest changes, install dependencies, rebuild, and restart the application. Settings are preserved.

```bash
cd Vane
git pull origin master
```

```bash
npm i
```

```bash
npm run build
```

```bash
npm run start
```

--------------------------------

### Get current weather conditions

Source: https://context7.com/itzcrazykns/vane/llms.txt

Fetches live weather data from Open-Meteo for specified coordinates. Returns a structured weather object including temperature, humidity, wind speed, and condition. Supports Metric and Imperial units.

```bash
curl -X POST http://localhost:3000/api/weather \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 37.7749,
    "lng": -122.4194,
    "measureUnit": "Metric"
  }'
```

--------------------------------

### POST /api/weather — Get current weather conditions

Source: https://context7.com/itzcrazykns/vane/llms.txt

Fetches live weather data from Open-Meteo for given coordinates and returns a structured weather object with condition, icon name, temperature, humidity, and wind speed.

```APIDOC
## POST /api/weather — Get current weather conditions

### Description
Fetches live weather data from Open-Meteo for given coordinates and returns a structured weather object with condition, icon name, temperature, humidity, and wind speed.

### Method
POST

### Endpoint
/api/weather

### Request Body
- **lat** (number) - Required - The latitude coordinate.
- **lng** (number) - Required - The longitude coordinate.
- **measureUnit** (string) - Optional - The measurement unit for temperature and wind speed. Defaults to 'Metric'. Allowed values: Metric, Imperial.

### Request Example
```json
{
  "lat": 37.7749,
  "lng": -122.4194,
  "measureUnit": "Metric"
}
```

### Response
#### Success Response (200)
- **temperature** (number) - The current temperature.
- **condition** (string) - The current weather condition.
- **humidity** (number) - The current humidity percentage.
- **windSpeed** (number) - The current wind speed.
- **icon** (string) - The icon name representing the weather condition.
- **temperatureUnit** (string) - The unit of temperature (C or F).
- **windSpeedUnit** (string) - The unit of wind speed (m/s or mph).

#### Response Example
```json
{
  "temperature": 18,
  "condition": "Partly Cloudy",
  "humidity": 72,
  "windSpeed": 4.5,
  "icon": "cloudy-1-day",
  "temperatureUnit": "C",
  "windSpeedUnit": "m/s"
}
```
```

--------------------------------

### Streaming Search API Response Example

Source: https://context7.com/itzcrazykns/vane/llms.txt

This illustrates the Server-Sent Events (SSE) stream format for streaming search requests. Each line is a JSON object indicating the event type and data.

```json
{"type":"init","data":"Stream connected"}
{"type":"sources","data":[{"content":"...","metadata":{"title":"...","url":"..."}}]}
{"type":"response","data":"Recent transformer "}
{"type":"response","data":"advances include..."}
{"type":"done"}
```

--------------------------------

### Get Available Providers and Models

Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md

Retrieve a list of active providers and their available chat and embedding models. Use the 'id' for providerId and 'key' for model keys in search requests.

```json
{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "OpenAI",
      "chatModels": [
        {
          "name": "GPT 4 Omni Mini",
          "key": "gpt-4o-mini"
        },
        {
          "name": "GPT 4 Omni",
          "key": "gpt-4o"
        }
      ],
      "embeddingModels": [
        {
          "name": "Text Embedding 3 Large",
          "key": "text-embedding-3-large"
        }
      ]
    }
  ]
}
```

--------------------------------

### List Active Model Providers

Source: https://context7.com/itzcrazykns/vane/llms.txt

Call this endpoint first to get a list of all configured AI providers and their available chat and embedding models. The `providerId` obtained here is necessary for other API calls.

```bash
curl http://localhost:3000/api/providers
```

--------------------------------

### GET /api/discover — Browse curated news articles

Source: https://context7.com/itzcrazykns/vane/llms.txt

Returns a list of news articles for the given topic and mode, sourced from topic-specific sites via SearxNG Bing News.

```APIDOC
## GET /api/discover — Browse curated news articles

### Description
Returns a list of news articles for the given topic and mode, sourced from topic-specific sites via SearxNG Bing News.

### Method
GET

### Endpoint
/api/discover

### Query Parameters
- **topic** (string) - Optional - The topic of the news articles. Defaults to 'tech'. Allowed values: tech, finance, art, sports, entertainment.
- **mode** (string) - Optional - The search mode. Defaults to 'normal'. Allowed values: normal, preview.

### Request Example
```bash
# Normal mode — randomised multi-query results
curl "http://localhost:3000/api/discover?topic=tech&mode=normal"

# Preview mode — single fast query
curl "http://localhost:3000/api/discover?topic=finance&mode=preview"
```

### Response
#### Success Response (200)
- **blogs** (array) - List of curated news articles.
  - **title** (string) - The title of the news article.
  - **url** (string) - The URL of the news article.
  - **content** (string) - A snippet of the article content.
  - **thumbnail_src** (string) - The URL of the article thumbnail.

#### Response Example
```json
{
  "blogs": [
    {
      "title": "OpenAI releases new model",
      "url": "https://techcrunch.com/...",
      "content": "OpenAI today announced...",
      "thumbnail_src": "https://..."
    }
  ]
}
```
```

--------------------------------

### Get Available Providers and Models

Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md

Retrieves a list of all active providers and their available chat and embedding models. This information is necessary for making subsequent search requests.

```APIDOC
## GET /api/providers

### Description
Returns a list of all active providers with their available chat and embedding models.

### Method
GET

### Endpoint
/api/providers

### Response
#### Success Response (200)
- **providers** (array) - A list of provider objects.
  - **id** (string) - The unique identifier for the provider.
  - **name** (string) - The name of the provider (e.g., "OpenAI").
  - **chatModels** (array) - A list of available chat models for the provider.
    - **name** (string) - The display name of the chat model.
    - **key** (string) - The identifier for the chat model to be used in requests.
  - **embeddingModels** (array) - A list of available embedding models for the provider.
    - **name** (string) - The display name of the embedding model.
    - **key** (string) - The identifier for the embedding model to be used in requests.

#### Response Example
```json
{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "OpenAI",
      "chatModels": [
        {
          "name": "GPT 4 Omni Mini",
          "key": "gpt-4o-mini"
        },
        {
          "name": "GPT 4 Omni",
          "key": "gpt-4o"
        }
      ],
      "embeddingModels": [
        {
          "name": "Text Embedding 3 Large",
          "key": "text-embedding-3-large"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### GET /api/chats — List all saved chats

Source: https://context7.com/itzcrazykns/vane/llms.txt

Returns all persisted chat sessions in reverse chronological order.

```APIDOC
## GET /api/chats — List all saved chats

### Description
Returns all persisted chat sessions in reverse chronological order.

### Method
GET

### Endpoint
/api/chats

### Response
#### Success Response (200)
- **chats** (array) - A list of saved chat sessions.
  - **id** (string) - The unique identifier for the chat session.
  - **title** (string) - The title of the chat session.
  - **createdAt** (string) - The timestamp when the chat session was created.
  - **sources** (array) - List of sources used in the chat session.
  - **files** (array) - List of files associated with the chat session.

#### Response Example
```json
{
  "chats": [
    {
      "id": "chat-uuid-001",
      "title": "Explain quantum entanglement simply",
      "createdAt": "2024-11-01T10:30:00.000Z",
      "sources": ["web"],
      "files": []
    }
  ]
}
```
```

--------------------------------

### Streaming Search Response (SSE)

Source: https://github.com/itzcrazykns/vane/blob/master/docs/API/SEARCH.md

When streaming is enabled (stream: true), the API returns Server-Sent Events (SSE). Each line is a newline-delimited JSON object. This example shows the structure of different message types within the stream.

```text
{"type":"init","data":"Stream connected"}
{"type":"sources","data":[{"content":"...","metadata":{"title":"...","url":"..."}},...]}
{"type":"response","data":"Vane is an "}
{"type":"response","data":"innovative, open-source "}
{"type":"response","data":"AI-powered search engine..."}
{"type":"done"}
```

--------------------------------

### Run Vane with Existing SearxNG Instance (Docker)

Source: https://github.com/itzcrazykns/vane/blob/master/README.md

Use this command to run the slim version of Vane when you already have a SearxNG instance. Ensure your SearxNG instance has JSON format and Wolfram Alpha enabled. Replace `http://your-searxng-url:8080` with your actual SearxNG URL.

```bash
docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:slim-latest
```

--------------------------------

### GET /api/chats/[id] — Get a specific chat with messages

Source: https://context7.com/itzcrazykns/vane/llms.txt

Retrieves a single chat and all its associated messages (with stored response blocks).

```APIDOC
## GET /api/chats/[id] — Get a specific chat with messages

### Description
Retrieves a single chat and all its associated messages (with stored response blocks).

### Method
GET

### Endpoint
/api/chats/[id]

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the chat session.

### Response
#### Success Response (200)
- **chat** (object) - The chat session details.
  - **id** (string) - The unique identifier for the chat session.
  - **title** (string) - The title of the chat session.
  - **createdAt** (string) - The timestamp when the chat session was created.
  - **sources** (array) - List of sources used in the chat session.
  - **files** (array) - List of files associated with the chat session.
- **messages** (array) - A list of messages within the chat session.
  - **id** (number) - The message ID.
  - **messageId** (string) - The unique message identifier.
  - **chatId** (string) - The ID of the chat session this message belongs to.
  - **backendId** (string) - The backend identifier for the message.
  - **query** (string) - The user's query.
  - **createdAt** (string) - The timestamp when the message was created.
  - **status** (string) - The status of the message processing.
  - **responseBlocks** (array) - The blocks of the response.
    - **id** (string) - The ID of the response block.
    - **type** (string) - The type of the response block (e.g., 'source', 'text').
    - **data** (any) - The data content of the response block.

#### Response Example
```json
{
  "chat": {
    "id": "chat-uuid-001",
    "title": "Explain quantum entanglement simply",
    "createdAt": "2024-11-01T10:30:00.000Z",
    "sources": ["web"],
    "files": []
  },
  "messages": [
    {
      "id": 1,
      "messageId": "msg-uuid-001",
      "chatId": "chat-uuid-001",
      "backendId": "session-uuid",
      "query": "Explain quantum entanglement simply",
      "createdAt": "2024-11-01T10:30:00.000Z",
      "status": "completed",
      "responseBlocks": [
        { "id": "b1", "type": "source", "data": [...] },
        { "id": "b2", "type": "text",   "data": "Quantum entanglement is..." }
      ]
    }
  ]
}
```
```

--------------------------------

### Read application configuration

Source: https://context7.com/itzcrazykns/vane/llms.txt

Retrieves the current application configuration, including preferences, personalization, search settings, and provider list. This is useful for understanding the current state of the application.

```bash
curl http://localhost:3000/api/config

# Response 200
{
  "values": {
    "version": 1,
    "setupComplete": true,
    "preferences": { "measureUnit": "Metric" },
    "personalization": { "systemInstructions": "" },
    "modelProviders": [ { "id": "...", "name": "OpenAI", ... } ],
    "search": { "searxngApiUrl": "http://localhost:4000" }
  },
  "fields": {
    "preferences": [...],
    "personalization": [...],
    "modelProviders": [...],
    "search": [...] 
  }
}
```

--------------------------------

### Read application configuration

Source: https://context7.com/itzcrazykns/vane/llms.txt

Returns the current application configuration, including preferences, personalization settings, search settings, and the list of available model providers. It also provides UI field definitions for the settings panel.

```APIDOC
## GET /api/config

### Description
Reads the current application configuration, including preferences, personalization, search settings, and provider list, along with UI field definitions for the settings panel.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **values** (object) - Contains the current configuration values.
  - **version** (number) - The configuration version.
  - **setupComplete** (boolean) - Indicates if the initial setup is complete.
  - **preferences** (object) - User preferences.
  - **personalization** (object) - Personalization settings.
  - **modelProviders** (array) - List of available model providers.
  - **search** (object) - Search-related configuration.
- **fields** (object) - UI field definitions for the settings panel.
```

--------------------------------

### Update Vane using Docker (Pre-built Images)

Source: https://github.com/itzcrazykns/vane/blob/master/docs/installation/UPDATING.md

Pull the latest Vane Docker image and restart the container. Settings are preserved.

```bash
docker pull itzcrazykns1337/vane:latest
docker stop vane
docker rm vane
docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest
```

```bash
docker pull itzcrazykns1337/vane:slim-latest
docker stop vane
docker rm vane
docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:slim-latest
```

--------------------------------

### Register New Model Provider

Source: https://context7.com/itzcrazykns/vane/llms.txt

Adds a new AI provider, such as a local Ollama server or an OpenAI key, to the Vane configuration. The response includes the newly created provider's details and its discovered models.

```bash
curl -X POST http://localhost:3000/api/providers \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ollama",
    "name": "Local Ollama",
    "config": {
      "apiUrl": "http://localhost:11434"
    }
  }'
```

--------------------------------

### Get a specific chat with messages

Source: https://context7.com/itzcrazykns/vane/llms.txt

Retrieves a single chat session by its ID, including all associated messages and response blocks. Useful for resuming or reviewing a specific conversation.

```bash
curl "http://localhost:3000/api/chats/chat-uuid-001"
```

--------------------------------

### Update Vane using Docker (Build from Source)

Source: https://github.com/itzcrazykns/vane/blob/master/docs/installation/UPDATING.md

Update Vane from source by pulling latest changes, rebuilding the Docker image, and restarting the container. Ensure you are in the Vane directory.

```bash
cd Vane
git pull origin master
```

```bash
docker build -t vane .
```

```bash
docker stop vane
docker rm vane
docker run -p 3000:3000 -p 8080:8080 --name vane vane
```

--------------------------------

### Register a New Model Provider

Source: https://context7.com/itzcrazykns/vane/llms.txt

Adds a new provider instance (e.g. a local Ollama server or a new OpenAI key) and persists it to the app config. Returns the created provider with its discovered model list.

```APIDOC
## POST /api/providers — Register a new model provider

### Description
Adds a new provider instance (e.g. a local Ollama server or a new OpenAI key) and persists it to the app config. Returns the created provider with its discovered model list.

### Method
POST

### Endpoint
/api/providers

### Parameters
#### Request Body
- **type** (string) - Required - The type of the provider (e.g., "ollama", "openai").
- **name** (string) - Required - A display name for the provider.
- **config** (object) - Required - Configuration specific to the provider type.
  - **apiUrl** (string) - Required for some provider types (e.g., Ollama) - The API endpoint URL.

### Request Example
```json
{
  "type": "ollama",
  "name": "Local Ollama",
  "config": {
    "apiUrl": "http://localhost:11434"
  }
}
```

### Response
#### Success Response (200)
- **provider** (object) - The newly created provider configuration.
  - **id** (string) - The unique identifier for the provider.
  - **name** (string) - The display name of the provider.
  - **type** (string) - The type of the provider.
  - **chatModels** (array) - List of available chat models for this provider.
    - **name** (string) - The display name of the chat model.
    - **key** (string) - The identifier for the chat model.
  - **embeddingModels** (array) - List of available embedding models for this provider.
    - **name** (string) - The display name of the embedding model.
    - **key** (string) - The identifier for the embedding model.

### Response Example
```json
{
  "provider": {
    "id": "a1b2c3d4-...",
    "name": "Local Ollama",
    "type": "ollama",
    "chatModels": [
      { "name": "llama3.1:8b", "key": "llama3.1:8b" }
    ],
    "embeddingModels": [
      { "name": "nomic-embed-text", "key": "nomic-embed-text" }
    ]
  }
}
```
```

--------------------------------

### Generate follow-up query suggestions

Source: https://context7.com/itzcrazykns/vane/llms.txt

Given conversation history, this endpoint returns AI-generated follow-up question suggestions to enhance user interaction. Requires chat history and chat model configuration.

```bash
curl -X POST http://localhost:3000/api/suggestions \
  -H "Content-Type: application/json" \
  -d '{
    "chatHistory": [
      ["human",     "What is the James Webb Space Telescope?"],
      ["assistant", "The JWST is NASA's flagship infrared observatory..."]
    ],
    "chatModel": { "providerId": "550e8400-...", "key": "gpt-4o-mini" }
  }'
```

--------------------------------

### AI-powered image search with context

Source: https://context7.com/itzcrazykns/vane/llms.txt

Generates an optimized image search query from conversation context using a chat model and fetches results via SearxNG. Requires a query, chat history, and chat model configuration.

```bash
curl -X POST http://localhost:3000/api/images \
  -H "Content-Type: application/json" \
  -d '{
    "query": "golden gate bridge at sunset",
    "chatHistory": [
      ["human",     "I am planning a trip to San Francisco."],
      ["assistant", "San Francisco is beautiful!"]
    ],
    "chatModel": { "providerId": "550e8400-...", "key": "gpt-4o-mini" }
  }'
```

--------------------------------

### File Upload for Semantic Search

Source: https://context7.com/itzcrazykns/vane/llms.txt

This endpoint accepts files via multipart/form-data for chunking, embedding, and local storage. It returns file IDs that can be used in `/api/chat` requests.

```bash
curl -X POST http://localhost:3000/api/uploads \
  -F "files=@/path/to/research-paper.pdf" \
  -F "files=@/path/to/notes.txt" \
  -F "embedding_model_key=text-embedding-3-large" \
  -F "embedding_model_provider_id=550e8400-..."
```

--------------------------------

### POST /api/suggestions — Generate follow-up query suggestions

Source: https://context7.com/itzcrazykns/vane/llms.txt

Given conversation history, returns AI-generated follow-up question suggestions to display after an answer.

```APIDOC
## POST /api/suggestions — Generate follow-up query suggestions

### Description
Given conversation history, returns AI-generated follow-up question suggestions to display after an answer.

### Method
POST

### Endpoint
/api/suggestions

### Request Body
- **chatHistory** (array) - Required - The conversation history.
- **chatModel** (object) - Required - The chat model configuration.
  - **providerId** (string) - Required - The provider ID of the chat model.
  - **key** (string) - Required - The API key for the chat model.

### Request Example
```json
{
  "chatHistory": [
    ["human",     "What is the James Webb Space Telescope?"],
    ["assistant", "The JWST is NASA's flagship infrared observatory..."]
  ],
  "chatModel": { "providerId": "550e8400-...", "key": "gpt-4o-mini" }
}
```

### Response
#### Success Response (200)
- **suggestions** (array) - A list of suggested follow-up questions.

#### Response Example
```json
{
  "suggestions": [
    "What discoveries has JWST made so far?",
    "How does JWST differ from Hubble?",
    "What is the operational lifespan of JWST?"
  ]
}
```
```

--------------------------------

### List Active Model Providers

Source: https://context7.com/itzcrazykns/vane/llms.txt

Returns all configured AI providers with their available chat and embedding models. Call this first to obtain `providerId` values needed by every other endpoint.

```APIDOC
## GET /api/providers — List active model providers

### Description
Returns all configured AI providers with their available chat and embedding models. Call this first to obtain `providerId` values needed by every other endpoint.

### Method
GET

### Endpoint
/api/providers

### Response
#### Success Response (200)
- **providers** (array) - A list of configured AI providers.
  - **id** (string) - The unique identifier for the provider.
  - **name** (string) - The display name of the provider.
  - **chatModels** (array) - List of available chat models for this provider.
    - **name** (string) - The display name of the chat model.
    - **key** (string) - The identifier for the chat model.
  - **embeddingModels** (array) - List of available embedding models for this provider.
    - **name** (string) - The display name of the embedding model.
    - **key** (string) - The identifier for the embedding model.

### Response Example
```json
{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "OpenAI",
      "chatModels": [
        { "name": "GPT 4 Omni Mini", "key": "gpt-4o-mini" },
        { "name": "GPT 4 Omni",      "key": "gpt-4o" }
      ],
      "embeddingModels": [
        { "name": "Text Embedding 3 Large", "key": "text-embedding-3-large" }
      ]
    }
  ]
}
```
```

--------------------------------

### AI-powered video search

Source: https://context7.com/itzcrazykns/vane/llms.txt

Similar to image search, this endpoint generates a video search query from context and returns video results, including embeddable iframe sources. Requires a query, chat history, and chat model configuration.

```bash
curl -X POST http://localhost:3000/api/videos \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to make sourdough bread",
    "chatHistory": [],
    "chatModel": { "providerId": "550e8400-...", "key": "gpt-4o-mini" }
  }'
```

--------------------------------

### POST /api/reconnect/[id]

Source: https://context7.com/itzcrazykns/vane/llms.txt

Reattaches to an in-progress search session identified by its session ID. Replays all previously emitted events and then continues live.

```APIDOC
## POST /api/reconnect/[id]

### Description
Reattaches to an in-progress search session identified by its session ID. Replays all previously emitted events and then continues live. Useful for reconnecting after a network drop.

### Method
POST

### Endpoint
/api/reconnect/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID to reconnect to.

### Request Example
```bash
SESSION_ID="session-uuid-from-prior-chat-response"

curl -X POST "http://localhost:3000/api/reconnect/${SESSION_ID}"
```

### Response
Returns the same SSE block stream as `/api/chat`, starting from the beginning of the session.
```

--------------------------------

### Programmatic Search

Source: https://context7.com/itzcrazykns/vane/llms.txt

The primary API for integrating Vane into external applications. Runs the full classify → research → write pipeline and returns either a complete JSON response or an SSE stream. Requires `query` and `sources`; all other fields have defaults.

```APIDOC
## POST /api/search — Programmatic search (non-streaming & streaming)

### Description
The primary API for integrating Vane into external applications. Runs the full classify → research → write pipeline and returns either a complete JSON response or an SSE stream. Requires `query` and `sources`; all other fields have defaults.

### Method
POST

### Endpoint
/api/search

### Parameters
#### Request Body
- **query** (string) - Required - The user's search query.
- **sources** (array) - Required - A list of sources to consider for the search (e.g., ["web", "files", "docs"]).
- **optimizationMode** (string) - Optional - Controls the research depth ('speed', 'balanced', 'quality'). Defaults to 'balanced'.
- **stream** (boolean) - Optional - If true, returns results as a Server-Sent Events (SSE) stream. Defaults to false.
- **providerId** (string) - Optional - The ID of the AI provider to use for generating the answer. Defaults to the first available provider.
- **chatModelKey** (string) - Optional - The key of the specific chat model to use. Defaults to the provider's default chat model.
- **embeddingModelKey** (string) - Optional - The key of the specific embedding model to use. Defaults to the provider's default embedding model.

### Request Example
```bash
curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{ 
    "query": "What is the weather today?",
    "sources": ["web"],
    "stream": true
  }'
```

### Response
#### Success Response (200)
- **Non-streaming**: A JSON object containing the answer, citations, and other metadata.
- **Streaming**: A Server-Sent Events (SSE) stream where each event contains a chunk of the answer.

#### Response Example (Non-streaming)
```json
{
  "answer": "The weather today is sunny with a high of 75°F.",
  "citations": [
    {
      "url": "http://example.com/weather",
      "title": "Local Weather Forecast"
    }
  ],
  "metadata": { ... }
}
```

#### Response Example (Streaming - SSE)
```
data: {"answer": "The weather today"}

data: {"answer": " is sunny"}

data: {"answer": " with a high of 75°F."}

data: {"citations": [{"url": "http://example.com/weather", "title": "Local Weather Forecast"}]}

```
```

--------------------------------

### Browse curated news articles

Source: https://context7.com/itzcrazykns/vane/llms.txt

Fetches news articles for a given topic and mode, sourced from topic-specific sites via SearxNG Bing News. Supports 'normal' (randomized multi-query) and 'preview' (single fast query) modes.

```bash
curl "http://localhost:3000/api/discover?topic=tech&mode=normal"
```

```bash
curl "http://localhost:3000/api/discover?topic=finance&mode=preview"
```

--------------------------------

### POST /api/uploads

Source: https://context7.com/itzcrazykns/vane/llms.txt

Uploads files for semantic search. Files are chunked, embedded, and stored locally.

```APIDOC
## POST /api/uploads

### Description
Uploads files for semantic search. Accepts one or more files as `multipart/form-data`. Each file is chunked, embedded, and stored locally. Returns file IDs to pass as `files` in `/api/chat` requests.

### Method
POST

### Endpoint
/api/uploads

### Parameters
#### Request Body
- **files** (file) - Required - One or more files to upload.
- **embedding_model_key** (string) - Required - The key for the embedding model to use.
- **embedding_model_provider_id** (string) - Required - The provider ID for the embedding model.

### Request Example
```bash
curl -X POST http://localhost:3000/api/uploads \
  -F "files=@/path/to/research-paper.pdf" \
  -F "files=@/path/to/notes.txt" \
  -F "embedding_model_key=text-embedding-3-large" \
  -F "embedding_model_provider_id=550e8400-..."
```

### Response
#### Success Response (200)
- **files** (array) - An array of file objects, each containing `fileId`, `fileName`, and `fileExtension`.
  - **fileId** (string) - The unique identifier for the uploaded file.
  - **fileName** (string) - The name of the uploaded file.
  - **fileExtension** (string) - The extension of the uploaded file.

#### Response Example
```json
{
  "files": [
    { "fileId": "a3f8...", "fileName": "research-paper.pdf", "fileExtension": "pdf" },
    { "fileId": "7c21...", "fileName": "notes.txt",          "fileExtension": "txt" }
  ]
}
```

**Supported MIME types:** `application/pdf` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `text/plain`
```

--------------------------------

### Programmatic Search API

Source: https://context7.com/itzcrazykns/vane/llms.txt

The main API for external application integration. This endpoint executes the full Vane search pipeline, returning either a complete JSON response or an SSE stream. Requires `query` and `sources` parameters; other fields have default values.

```bash

```

--------------------------------

### Update a single configuration key

Source: https://context7.com/itzcrazykns/vane/llms.txt

Saves a key/value pair to the persistent app configuration. Ensure both 'key' and 'value' are provided in the request body. Used for modifying application settings.

```bash
curl -X POST http://localhost:3000/api/config \
  -H "Content-Type: application/json" \
  -d '{ 
    "key":   "preferences.measureUnit",
    "value": "Imperial"
  }'

# Response 200
{ "message": "Config updated successfully." }

# Response 400 (missing key or value)
{ "message": "Key and value are required." }
```

--------------------------------

### POST /api/videos — AI-powered video search

Source: https://context7.com/itzcrazykns/vane/llms.txt

Same pattern as /api/images but returns video results including iframe_src for embeddable players.

```APIDOC
## POST /api/videos — AI-powered video search

### Description
Same pattern as `/api/images` but returns video results including `iframe_src` for embeddable players.

### Method
POST

### Endpoint
/api/videos

### Request Body
- **query** (string) - Required - The search query.
- **chatHistory** (array) - Optional - The conversation history.
- **chatModel** (object) - Required - The chat model configuration.
  - **providerId** (string) - Required - The provider ID of the chat model.
  - **key** (string) - Required - The API key for the chat model.

### Request Example
```json
{
  "query": "how to make sourdough bread",
  "chatHistory": [],
  "chatModel": { "providerId": "550e8400-...", "key": "gpt-4o-mini" }
}
```

### Response
#### Success Response (200)
- **videos** (array) - List of video search results.
  - **title** (string) - The title of the video.
  - **url** (string) - The URL of the video.
  - **iframe_src** (string) - The embeddable source URL for the video player.
  - **thumbnail** (string) - The URL of the video thumbnail.

#### Response Example
```json
{
  "videos": [
    {
      "title": "Beginner Sourdough Tutorial",
      "url": "https://www.youtube.com/watch?v=...",
      "iframe_src": "https://www.youtube.com/embed/...",
      "thumbnail": "https://i.ytimg.com/vi/.../hqdefault.jpg"
    }
  ]
}
```
```

--------------------------------

### Docker Compose Configuration

Source: https://context7.com/itzcrazykns/vane/llms.txt

Defines the Vane service for deployment using Docker Compose. This configuration includes volume mounting for persistent data and specifies the image to use.

```yaml
# docker-compose.yaml
services:
  vane:
    image: itzcrazykns1337/vane:latest
    ports:
      - '3000:3000'
    volumes:
      - data:/home/vane/data
    restart: unless-stopped

volumes:
  data:
    name: 'vane-data'
```

--------------------------------

### POST /api/chat

Source: https://context7.com/itzcrazykns/vane/llms.txt

Powers the Vane web UI chat. Supports streaming responses via SSE and includes persistent chat storage.

```APIDOC
## POST /api/chat

### Description
Powers the Vane web UI chat. Supports streaming responses via SSE and includes persistent chat storage. Identical pipeline to `/api/search` but adds persistent chat/message storage, file attachment support, suggestion and widget blocks, and reconnection via session IDs. Responses are newline-delimited JSON blocks over SSE.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **message** (object) - Required - The chat message details, including `messageId`, `chatId`, and `content`.
- **optimizationMode** (string) - Required - The optimization mode for the chat. Values: `"speed"` | `"balanced"` | `"quality"`.
- **sources** (array) - Required - The sources to search within. Values: `"web"` | `"academic"` | `"discussions"`.
- **history** (array) - Optional - The conversation history.
- **files** (array) - Optional - An array of file IDs to include in the chat.
- **chatModel** (object) - Required - The chat model configuration, including providerId and key.
- **embeddingModel** (object) - Required - The embedding model configuration, including providerId and key.
- **systemInstructions** (string) - Optional - System-level instructions for the chat.

### Request Example
```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-uuid-001",
      "chatId":    "chat-uuid-001",
      "content":   "Explain quantum entanglement simply"
    },
    "optimizationMode": "quality",
    "sources": ["web"],
    "history": [],
    "files": [],
    "chatModel":      { "providerId": "550e8400-...", "key": "gpt-4o" },
    "embeddingModel": { "providerId": "550e8400-...", "key": "text-embedding-3-large" },
    "systemInstructions": "Use simple analogies."
  }'
```

### Response
#### Streaming Response Example (SSE)
```
{"type":"block","block":{"id":"b1","type":"research","data":{"subSteps":[]}}}
{"type":"updateBlock","blockId":"b1","patch":[{"op":"replace","path":"/data/subSteps/0/searching","value":["quantum entanglement"]}]}
{"type":"researchComplete"}
{"type":"block","block":{"id":"b2","type":"source","data":[{"content":"...","metadata":{}}]}}
{"type":"block","block":{"id":"b3","type":"text","data":"Quantum entanglement is..."}}
{"type":"updateBlock","blockId":"b3","patch":[{"op":"replace","path":"/data","value":"Quantum entanglement is a phenomenon..."}]}
{"type":"messageEnd"}
```

**Block types emitted:** `research` | `source` | `text` | `widget` | `suggestion`
```

--------------------------------

### UI Chat Endpoint (Streaming SSE)

Source: https://context7.com/itzcrazykns/vane/llms.txt

This endpoint powers the Vane web UI, providing a chat interface with persistent message storage and file attachment support. Responses are delivered as newline-delimited JSON blocks over SSE.

```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-uuid-001",
      "chatId":    "chat-uuid-001",
      "content":   "Explain quantum entanglement simply"
    },
    "optimizationMode": "quality",
    "sources": ["web"],
    "history": [],
    "files": [],
    "chatModel":      { "providerId": "550e8400-...", "key": "gpt-4o" },
    "embeddingModel": { "providerId": "550e8400-...", "key": "text-embedding-3-large" },
    "systemInstructions": "Use simple analogies."
  }'
```

--------------------------------

### Streaming Search API Request

Source: https://context7.com/itzcrazykns/vane/llms.txt

This endpoint is used for search queries that require real-time, streaming responses. Set `stream` to `true` to enable this functionality. The response will be a stream of Server-Sent Events (SSE).

```bash
curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{ ..., "stream": true }'
```

--------------------------------

### List all saved chats

Source: https://context7.com/itzcrazykns/vane/llms.txt

Returns a list of all persisted chat sessions in reverse chronological order. Useful for retrieving a history of user interactions.

```bash
curl http://localhost:3000/api/chats
```

--------------------------------

### Update a single configuration key

Source: https://context7.com/itzcrazykns/vane/llms.txt

Saves a key/value pair to the persistent application configuration.

```APIDOC
## POST /api/config

### Description
Updates a single configuration key with a new value in the persistent application configuration.

### Method
POST

### Endpoint
/api/config

### Parameters
#### Request Body
- **key** (string) - Required - The configuration key to update (e.g., "preferences.measureUnit").
- **value** (any) - Required - The new value for the configuration key.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful update.

#### Error Response (400)
- **message** (string) - Message indicating that key and value are required.
```