AI API

AI provider endpoints for model selection, chat completion, and cost estimation

AI API

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

GET /api/ai/health

Returns the availability status of configured AI providers.

Response

{
  "status": "healthy",
  "providers": {
    "openrouter": true
  },
  "timestamp": "2026-03-19T00:00:00Z"
}

The 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

GET /api/ai/models

Returns all available AI models across providers.

Response

{
  "models": [
    {
      "id": "anthropic/claude-sonnet-4-20250514",
      "provider": "openrouter"
    }
  ],
  "count": 1,
  "openrouter": 1,
  "timestamp": "2026-03-19T00:00:00Z"
}

Errors

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"
}

Select model

POST /api/ai/models/select

Automatically selects the best model for a given task type.

Request body

Field	Type	Required	Description
taskType	string	No	Type of task (default: general)

Response

{
  "model": {
    "id": "anthropic/claude-sonnet-4-20250514",
    "provider": "openrouter"
  },
  "taskType": "general",
  "timestamp": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
404	No models available

Chat completion

POST /api/ai/chat

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.

Errors

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

Estimate the cost of a request based on token counts and model pricing.

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"
}

Errors

Code	Description
400	Model, inputTokens, and outputTokens are all required