API Reference

Octo Router exposes an OpenAI-compatible interface for completions, health monitoring, and administrative endpoints for cluster management.

System Health

GET /health

Returns the current server health and the count of active providers.

Example Response

{
  "status": "healthy",
  "providers": 5
}

Chat Completions

POST /v1/chat/completions

This endpoint is compatible with the OpenAI Chat Completions API.

Request Body

Standard OpenAI request body. Octo Router ignores the model field if a routing policy is active.

Success Response

Octo Router returns a flattened response for simplicity:

{
  "message": "Hello! How can I help you today?",
  "role": "assistant",
  "provider": "openai",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  },
  "cost_usd": 0.00045
}

Example Request

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ROUTER_KEY" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Admin API

Administrative endpoints require the same authentication key if configured.

Get System Status

GET /admin/status

Returns health status, circuit breaker states, and current routing strategy.

Get Usage History

GET /admin/usage?date=YYYY-MM-DD

Returns token usage and cost statistics for the specified date (defaults to today).

Reset Budgets

POST /admin/budgets/reset?provider=openai

Resets the budget usage for the specified provider.

Reload Configuration

POST /admin/config/reload

Triggers a zero-downtime hot-reload of the config.yaml file.