API Documentation

derouter.ai exposes a REST API for account management, Client Key management, and usage tracking.

Authentication

All requests authenticate via the Authorization header. There are two types of keys — each with different permissions:

Base URL

https://cf-api.derouter.ai

Endpoint Overview

Account

Requires Account Key

GET /balance

Returns your account balance, locked balance, and available balance.

curl https://cf-api.derouter.ai/balance \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY"

Response:

{
  "balance": "100.0000",
  "locked_balance": "20.0000",
  "available": "80.0000"
}

Client Key Management

Requires Account Key

GET /sub-keys

Lists all active Client Keys with their balance and usage.

curl https://cf-api.derouter.ai/sub-keys \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY"

Response:

{
  "subKeys": [
    {
      "id": "uuid",
      "label": "Client A",
      "keyId": "sk-ant-abc...",
      "key": "sk-ant-abc...full",
      "budgetVirtual": 50,
      "spentVirtual": 12.5,
      "remainingVirtual": 37.5,
      "rpmLimit": 60,
      "concurrentLimit": 5,
      "displayMultiplier": 1,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /sub-keys

Creates a new Client Key with an allocated budget from your main balance.

curl -X POST https://cf-api.derouter.ai/sub-keys \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budgetVirtual": 25, "label": "Client B"}'

Parameters:

• budgetVirtual (required) — Budget in USD to allocate.
• label (optional) — A name for this key.
• rpmLimit (optional) — Requests per minute limit (default 60).

Response:

{
  "id": "uuid",
  "key": "sk-ant-new-key-full",
  "keyId": "sk-ant-new...",
  "label": "Client B",
  "budgetVirtual": 25,
  "rpmLimit": 30,
  "concurrentLimit": 5
}

PUT /sub-keys/:id

Updates an existing Client Key's label, rate limit, or adds budget.

curl -X PUT https://cf-api.derouter.ai/sub-keys/:id \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addBudgetVirtual": 10, "label": "Client B Pro"}'

Parameters:

• :id (required, in URL) — The Client Key ID to update.
• label (optional) — New label.
• rpmLimit (optional) — New RPM limit (1–60).
• addBudgetVirtual (optional) — Additional budget to add (deducted from main balance).
• displayMultiplier (optional) — Display multiplier (min 1).

DELETE /sub-keys/:id

Deletes a Client Key. Unspent budget is returned to your main balance.

curl -X DELETE https://cf-api.derouter.ai/sub-keys/:id \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY"

GET /usage-logs

Retrieves paginated usage logs. Optionally filter by Client Key or account-only.

curl "https://cf-api.derouter.ai/usage-logs?page=1&limit=20" \
  -H "Authorization: Bearer sk-ant-YOUR_ACCOUNT_KEY"

Query parameters:

• page (optional) — Page number, default 1.
• limit (optional) — Items per page, default 20, max 100.
• subKeyId (optional) — Filter by a specific Client Key ID.
• accountOnly (optional) — If true, only show account-level usage (exclude Client Keys).

Response:

{
  "data": [
    {
      "request_id": "req_abc123",
      "model": "claude-sonnet-4-6-20250514",
      "input_tokens": 1500,
      "output_tokens": 800,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cost_usdc": 0.0023,
      "duration_ms": 2100,
      "created_at": "2025-06-01T12:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 150, "pages": 8 }
}

Client Key Self-Service

Requires Client Key — designed for downstream clients to query their own data

GET /sub-key/balance

Returns balance, rate limits, and usage summary for the authenticated Client Key.

curl https://cf-api.derouter.ai/sub-key/balance \
  -H "Authorization: Bearer sk-ant-YOUR_CLIENT_KEY"

Response:

{
  "budget": 200.0000,
  "spent": 50.0000,
  "remaining": 150.0000,
  "rpmLimit": 60,
  "concurrentLimit": 5,
  "label": "Client A",
  "usage": {
    "today":  { "requests": 5,   "inputTokens": 1000,  "outputTokens": 500,   "totalTokens": 1500,  "cost": 1.00 },
    "week":   { "requests": 30,  "inputTokens": 8000,  "outputTokens": 4000,  "totalTokens": 12000, "cost": 7.20 },
    "month":  { "requests": 120, "inputTokens": 50000, "outputTokens": 25000, "totalTokens": 75000, "cost": 34.00 },
    "total":  { "requests": 120, "inputTokens": 50000, "outputTokens": 25000, "totalTokens": 75000, "cost": 34.00 }
  }
}

GET /sub-key/usage-logs

Returns paginated request logs for the authenticated Client Key.

curl "https://cf-api.derouter.ai/sub-key/usage-logs?page=1&limit=20" \
  -H "Authorization: Bearer sk-ant-YOUR_CLIENT_KEY"

Query parameters:

• page (optional) — Page number, default 1.
• limit (optional) — Items per page, default 20, max 100.

Response:

{
  "data": [
    {
      "request_id": "req_abc123",
      "model": "claude-sonnet-4-6-20250514",
      "input_tokens": 1500,
      "output_tokens": 800,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cost_usdc": 0.0092,
      "duration_ms": 2100,
      "key_id": "sk-ant-abc...",
      "created_at": "2025-06-01T12:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 150, "pages": 8 }
}

Error Handling

All endpoints return standard HTTP status codes:

• 200 — Success.
• 401 — Missing or invalid API key.
• 400 — Invalid request body or parameters.
• 500 — Internal server error.

Error responses include a JSON body:

{ "error": "Invalid API key" }

Quick Start

Get started with derouter.ai using your preferred tool or client:

from openai import OpenAI
client = OpenAI(
    api_key="sk-ant-YOUR_KEY",
    base_url="https://api.derouter.ai/openai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

curl https://api.derouter.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-ant-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "Hello!"}]}'

curl https://api.derouter.ai/openai/v1/models \
  -H "Authorization: Bearer sk-ant-YOUR_KEY"

For Client Key management, referrals, and distribution strategies, see the Reseller Guide.