# What Are Vane's API Routes Used For? A Complete Guide to the Backend Architecture

> Explore Vane's API routes to understand its backend architecture. Learn how it validates requests loads LLM providers executes agents and streams data to your frontend.

- Repository: [Kushagra Srivastava/Vane](https://github.com/ItzCrazyKns/Vane)
- Tags: architecture
- Published: 2026-03-11

---

**Vane's API routes are serverless handlers that validate incoming requests, load LLM and embedding providers via the `ModelRegistry`, execute specialized agents for search, media, and weather, and return JSON or Server-Sent Event streams to the Next.js frontend.**

Vane is a Next.js 13+ application that exposes REST-style endpoints under `src/app/api/`. Each route acts as a thin adapter between the client and various AI services, handling everything from semantic web searches to file uploads and provider configuration. Understanding these endpoints is essential for debugging, extending, or integrating with the Vane platform.

## Core Search and AI Routes

### Semantic Search (`/api/search`)

The `/api/search` endpoint is the backbone of Vane's research capabilities. Located in [`src/app/api/search/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/search/route.ts), this `POST` handler accepts a query, loads the specified chat and embedding models from the `ModelRegistry`, and executes the `APISearchAgent`.

Key parameters include `sources` (array of strings like `"web"`, `"pdf"`, or `"searxng"`), `optimizationMode` (`"speed"` or `"quality"`), and `stream` (boolean). When streaming is enabled, the route returns an event-stream with types like `init`, `response`, `sources`, and `done`. For non-streaming requests, it returns a complete JSON object containing the message and source citations.

### Chat Suggestions (`/api/suggestions`)

The [`src/app/api/suggestions/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/suggestions/route.ts) file handles `POST` requests to generate quick-reply buttons. It calls `generateSuggestions` with the chat history and a loaded chat model to produce contextually relevant follow-up questions.

### Home Discovery (`/api/discover`)

Located at [`src/app/api/discover/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/discover/route.ts), this endpoint assembles a curated list of widgets (weather, stocks, news) based on user location and preferences. It returns a `POST` response containing widget configurations for the home dashboard.

## Media Generation Routes

### Video Search (`/api/videos`)

The [`src/app/api/videos/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/videos/route.ts) route accepts a `POST` request with a user query, loads the default chat model, and forwards the request to `handleVideoSearch`. This agent generates video suggestions or retrieves relevant video content based on the query context.

### Image Search (`/api/images`)

Similarly, [`src/app/api/images/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/images/route.ts) handles image generation and retrieval. It uses the `searchImages` function after loading the appropriate chat model, returning a list of image URLs and metadata matching the user's search terms.

## Utility and Data Routes

### Weather Information (`/api/weather`)

The [`src/app/api/weather/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/weather/route.ts) endpoint provides real-time weather data. It accepts `POST` requests with `lat`, `lng`, and `measureUnit` (Metric or Imperial), calls the Open-Meteo API, and maps weather codes to human-readable conditions and icon names in the response.

### File Uploads (`/api/uploads`)

Located in [`src/app/api/uploads/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/uploads/route.ts), this route handles multipart form-data uploads. It parses incoming files, computes embeddings using the specified embedding model via `UploadManager`, and returns processed metadata including file names, sizes, and embedding IDs. Required body parameters include `embedding_model_key` and `embedding_model_provider_id`.

## Chat Session Management

### Chat Lifecycle (`/api/chats` and `/api/chats/[id]`)

The [`src/app/api/chats/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chats/route.ts) file supports `GET` to list all user sessions and `POST` to create new ones. For individual chat operations, `src/app/api/chats/[id]/route.ts` handles `GET` (retrieve history), `PATCH` (rename), and `DELETE` (remove) operations on specific conversation threads.

### Message Handling (`/api/chat`)

Real-time messaging flows through [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts). This `POST` endpoint sends user messages to the active LLM and supports streaming responses for real-time token delivery.

### Stream Reconnection (`/api/reconnect/[id]`)

When network interruptions occur, `src/app/api/reconnect/[id]/route.ts` allows clients to `POST` to re-establish lost Server-Sent Event (SSE) connections for ongoing chat streams, ensuring continuity during long-running generations.

## Configuration and Provider Management

### Model Providers (`/api/providers`)

The [`src/app/api/providers/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/providers/route.ts) route supports `GET` to list active providers (filtering out errored chat models) and `POST` to register new providers. Each provider requires a `type`, `name`, and `config` object containing API keys.

For individual provider management, `src/app/api/providers/[id]/route.ts` handles `DELETE` to remove a provider via `ModelRegistry.removeProvider()` and `PATCH` to update configurations via `ModelRegistry.updateProvider()`.

### Application Configuration (`/api/config`)

Located in [`src/app/api/config/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/config/route.ts), this endpoint provides `GET` access to UI settings and active model data (enriched by `configManager` and `ModelRegistry`). The `POST` method updates specific configuration key-value pairs. The subdirectory [`src/app/api/config/setup-complete/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/config/setup-complete/route.ts) contains a specialized endpoint to mark the initial setup wizard as finished.

## Practical Code Examples

### Fetching Weather Data

```typescript
const response = await fetch('https://your-vane-instance.com/api/weather', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    lat: 37.7749,
    lng: -122.4194,
    measureUnit: 'Metric',
  }),
});

const data = await response.json();
// Returns: { temperature: 15, condition: 'Clear', icon: 'clear-day', ... }

```

### Executing a Semantic Search

```typescript
const searchResponse = await fetch('https://your-vane-instance.com/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'latest AI research papers',
    sources: ['web', 'pdf'],
    chatModel: { providerId: 'openai', key: 'gpt-4o' },
    embeddingModel: { providerId: 'openai', key: 'text-embedding-3-large' },
    history: [],
    optimizationMode: 'quality',
    stream: false,
  }),
});

const result = await searchResponse.json();
// Returns: { message: '...', sources: [{ title, url, snippet }, ...] }

```

### Handling Streaming Search with SSE

```typescript
const response = await fetch('https://your-vane-instance.com/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'Explain quantum computing',
    sources: ['web'],
    chatModel: { providerId: 'openai', key: 'gpt-4o' },
    stream: true,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader?.read() || {};
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log('Event type:', data.type, 'Content:', data.data);
    }
  }
}
// Events: {type:'init'}, {type:'response', data:'...'}, {type:'sources', data:[...]}, {type:'done'}

```

### Uploading Files for Embedding

```typescript
const formData = new FormData();
formData.append('files', fileInput.files[0]);
formData.append('embedding_model_key', 'text-embedding-3-large');
formData.append('embedding_model_provider_id', 'openai');

const uploadResponse = await fetch('https://your-vane-instance.com/api/uploads', {
  method: 'POST',
  body: formData,
});

const uploadResult = await uploadResponse.json();
// Returns: { files: [{ name, size, embeddingId, ... }, ...] }

```

### Managing Model Providers

```typescript
// List all providers
const providers = await fetch('https://your-vane-instance.com/api/providers')
  .then(r => r.json());

// Add a new provider
await fetch('https://your-vane-instance.com/api/providers', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'openai',
    name: 'OpenAI Production',
    config: { apiKey: process.env.OPENAI_API_KEY },
  }),
});

```

## Error Handling and Architecture Patterns

All routes in `src/app/api/` follow a consistent error-handling strategy. They wrap core logic in `try...catch` blocks, log errors to the console, and return standardized JSON responses with appropriate HTTP status codes (`400` for validation errors, `500` for server errors). This pattern ensures that clients receive predictable error structures regardless of which endpoint fails.

The routes rely heavily on the `ModelRegistry` singleton to instantiate chat and embedding models. This abstraction allows endpoints in [`src/app/api/search/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/search/route.ts), [`src/app/api/suggestions/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/suggestions/route.ts), and [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts) to remain provider-agnostic, supporting OpenAI, local models, and other backends without code changes.

## Summary

- **Search and AI**: `/api/search` runs semantic searches via `APISearchAgent`, `/api/suggestions` generates chat follow-ups, and `/api/discover` serves home widgets.
- **Media**: `/api/videos` and `/api/images` handle media generation through specialized agents like `handleVideoSearch` and `searchImages`.
- **Utilities**: `/api/weather` fetches Open-Meteo data, while `/api/uploads` processes files via `UploadManager`.
- **Chat Management**: Routes under `/api/chats/` and `/api/chat/` handle session CRUD and messaging, with `/api/reconnect/[id]` maintaining SSE streams.
- **Configuration**: `/api/providers` and `/api/config` manage LLM credentials and application settings through `ModelRegistry` and `configManager`.
- **Consistency**: All routes validate input, use centralized error handling, and support both JSON and streaming responses.

## Frequently Asked Questions

### How does Vane handle streaming responses in its API routes?

Vane's API routes check the `stream` parameter in the request body. When set to `true` (as implemented in [`src/app/api/search/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/search/route.ts) and [`src/app/api/chat/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/chat/route.ts)), the route returns a `text/event-stream` Content-Type and writes Server-Sent Events (SSE) to the response. Each event contains a JSON payload with a `type` field (e.g., `init`, `response`, `sources`, `done`) and a `data` field containing the actual content. If the connection drops, clients can use the `/api/reconnect/[id]` endpoint to resume the stream.

### What is the ModelRegistry and how do API routes use it?

The `ModelRegistry` is a singleton service that manages instantiated LLM and embedding providers. API routes like `/api/search`, `/api/suggestions`, and `/api/chat` call `ModelRegistry` methods to load the correct model based on the `providerId` and `key` specified in the request. This abstraction allows routes to remain agnostic to whether they are calling OpenAI, Ollama, or other backends, centralizing provider initialization and error handling in one location.

### How do I upload files to Vane's API for embedding?

Send a `POST` request to `/api/uploads` with `multipart/form-data` containing the file(s) and metadata fields `embedding_model_key` and `embedding_model_provider_id`. The route parses the form data using `UploadManager`, computes embeddings for each file using the specified model, and returns JSON metadata including unique embedding IDs that can be referenced in subsequent search queries. See [`src/app/api/uploads/route.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/app/api/uploads/route.ts) for the implementation details.

### Can external applications use Vane's API routes?

Yes, Vane's API routes are standard HTTP endpoints that accept JSON or FormData and return JSON or SSE streams. Any client capable of making HTTP requests—including mobile apps, Python scripts, or third-party services—can consume these endpoints. However, you must ensure proper CORS configuration on your Vane deployment and include the necessary authentication headers if you have implemented API key protection at the infrastructure level.