Chat Completions

POST /v1/chat/completions is an OpenAI-compatible endpoint. It requires an API key with the chat:write scope and is rate-limited per key.

Beta: mock provider

During beta this endpoint is served by a mock provider. It returns a deterministic response and does not call OpenAI, Anthropic, DeepSeek, Zhipu, or Kimi. The billing path (reserve → settle) is real and exercised on every call.

Request

# Use the model id from GET /v1/models (a platform admin must create the model and pricing first).
curl -X POST https://api.runne.run/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer rn_live_…' \
  -d '{
    "model": "<model-id-from-v1-models>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1000
  }'

Field	Type	Required	Notes
model	string	yes	"provider/model"; must match an id from GET /v1/models (no default)
messages	array	yes	min 1; role ∈ system | user | assistant
max_tokens	int	no	positive, default 1000

messages[].content must be a string (no multi-part content in beta).

Response

{
  "id": "chatcmpl-mock-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "mock-model",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "This is a mock response for demonstration purposes." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 2, "completion_tokens": 50, "total_tokens": 52 }
}

The mock response always returns completion_tokens: min(max_tokens, 50) and model: "mock-model".

Token billing

Every request runs the full billing pipeline:

1. Estimate — pessimistic cost from message length (chars/4) plus max_tokens at the model's output rate.
2. Reserve — atomically decrement the balance (fails with 402 insufficient_balance if the balance is too low).
3. Call the provider (mock in beta).
4. Settle — compute the actual cost:
   • actual ≤ estimated → refund the difference;
   • actual > estimated → debit the deficit (suspend the workspace if the deficit cannot be covered).

The request is billed against the workspace that owns the API key. Each request writes a usage_record plus ledger rows (reservation, settlement/refund/debit).

Errors

Status	When
401	missing/invalid/revoked key
403	key lacks chat:write, or workspace/customer suspended
404	unknown model or no pricing for the model
402	insufficient balance for reservation or deficit
429	per-key rate limit exceeded

See Errors for the full taxonomy.

Model catalog

GET /v1/models lists active models with current per-1k-token pricing:

curl https://api.runne.run/v1/models

Use the returned id as the model field. The catalog starts empty in beta — a platform admin must create the model and its pricing first. There is no default model: a value that isn't in the catalog returns 404 (no pricing). See Endpoints for the response shape.

Related

• API Keys — chat:write scope.
• Rate Limits & Quotas — limits and quota.
• Architecture — the ledger and deficit path.