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

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, 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 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, 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 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 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 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, 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 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. 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 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, 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 contains a specialized endpoint to mark the initial setup wizard as finished.

Practical Code Examples

Fetching Weather Data

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

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

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

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

// 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, src/app/api/suggestions/route.ts, and 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 and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}