Endpoints for interacting with AI models through a unified provider layer. These endpoints are served by the backend API service, not the web application. They are available at the backend base URL, which may differ from the web API base URL depending on your deployment.
These endpoints do not require session authentication. They are internal backend endpoints and are not exposed through the web application’s /api routes.
Health check
Returns the availability status of configured AI providers.
Response
{
"status": "healthy",
"providers": {
"openrouter": true
},
"timestamp": "2026-03-19T00:00:00Z"
}
status field is healthy when all providers are reachable and degraded when one or more are down.
Error response
When one or more providers fail, the response uses status: "error" and includes the error message:
{
"status": "error",
"error": "Provider connection failed"
}
| Code | Description |
|---|
| 503 | AI service unavailable |
List models
Returns all available AI models across providers.
Response
{
"models": [
{
"id": "anthropic/claude-sonnet-4-20250514",
"name": "Claude Sonnet",
"provider": "openrouter",
"description": "Fast, intelligent model for everyday tasks",
"tags": ["general", "coding"],
"inputCost": 3.0,
"outputCost": 15.0,
"contextWindow": 200000,
"available": true
}
],
"count": 1,
"openrouter": 1,
"timestamp": "2026-03-19T00:00:00Z"
}
| Field | Type | Description |
|---|
id | string | Model identifier |
name | string | Human-readable model name |
provider | string | Provider serving the model |
description | string | Short description of the model |
tags | string[] | Task categories the model is suited for |
inputCost | number | Cost per million input tokens (USD) |
outputCost | number | Cost per million output tokens (USD) |
contextWindow | number | Maximum context length in tokens |
available | boolean | Whether the model is currently available |
| Code | Description |
|---|
| 500 | Failed to fetch models |
List models by provider
GET /api/ai/models/:provider
Path parameters
| Parameter | Type | Description |
|---|
provider | string | Provider name (for example, openrouter) |
Response
{
"provider": "openrouter",
"models": [],
"count": 0,
"timestamp": "2026-03-19T00:00:00Z"
}
| Code | Description |
|---|
| 500 | Failed to fetch models for provider |
Select model
POST /api/ai/models/select
Request body
| Field | Type | Required | Description |
|---|
taskType | string | No | Type of task (default: general) |
Response
{
"model": {
"id": "anthropic/claude-sonnet-4-20250514",
"name": "Claude Sonnet",
"provider": "openrouter",
"description": "Fast, intelligent model for everyday tasks",
"tags": ["general", "coding"],
"inputCost": 3.0,
"outputCost": 15.0,
"contextWindow": 200000,
"available": true
},
"taskType": "general",
"timestamp": "2026-03-19T00:00:00Z"
}
| Code | Description |
|---|
| 404 | No models available |
| 500 | Internal server error |
Chat completion
Send a chat completion request through the unified AI provider layer. The model is auto-selected if not specified.
Request body
| Field | Type | Required | Description |
|---|
messages | array | Yes | Array of message objects with role (user, assistant, or system) and content |
model | string | No | Model ID. Auto-selected based on taskType if omitted. |
taskType | string | No | Used for auto-selection when model is omitted |
temperature | number | No | Sampling temperature |
top_p | number | No | Nucleus sampling parameter |
max_tokens | number | No | Maximum tokens in the response |
Example request
{
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"temperature": 0.7,
"max_tokens": 1024
}
Response
Returns the AI provider’s chat completion response. The exact shape depends on the provider used.
| Code | Description |
|---|
| 400 | Messages array is required and must be non-empty |
| 404 | No models available |
| 500 | AI provider error |
Estimate cost
POST /api/ai/estimate-cost
Request body
| Field | Type | Required | Description |
|---|
model | string | Yes | Model ID |
inputTokens | number | Yes | Number of input tokens |
outputTokens | number | Yes | Number of output tokens |
Response
{
"model": "anthropic/claude-sonnet-4-20250514",
"inputTokens": 1000,
"outputTokens": 500,
"estimatedCost": 0.0045,
"currency": "USD",
"timestamp": "2026-03-19T00:00:00Z"
}
| Code | Description |
|---|
| 400 | Model, inputTokens, and outputTokens are all required |
| 500 | Internal server error |
