Chat completions

Request body

The request is the standard OpenAI chat-completions body. The only field that changes your provider is model.

Example request

curl https://boldrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $BOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [
      { "role": "system", "content": "You are concise." },
      { "role": "user", "content": "What is an API gateway?" }
    ],
    "max_tokens": 256
  }'

Response

A non-streaming request returns a single chat.completion object, identical in shape to OpenAI's:

{
  "id": "chatcmpl-mq581fe5",
  "object": "chat.completion",
  "created": 1780923785,
  "model": "anthropic/claude-sonnet-4.6",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "An API gateway is..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 58,
    "total_tokens": 82,
    "completion_tokens_details": { "reasoning_tokens": 12 }
  }
}

Usage & billing

The usage object reports token counts, taken from the provider's own numbers when available and estimated otherwise. You are billed on these counts at the model's price - see Pricing & billing. Cache hits are reported under prompt_tokens_details.cached_tokens and billed at a discount (Prompt caching). Tokens a model spent thinking are reported under completion_tokens_details.reasoning_tokens. They are already included in completion_tokens and billed as output, the way providers bill them, even though the reasoning itself is not returned. The field appears only when the provider reports it. Even interrupted streams and client disconnects are metered for the partial output produced.

Response headers

Every gateway response carries headers describing how it was routed:

JSON mode & structured outputs

Constrain the model to emit JSON with response_format, using OpenAI's shape. { type: "json_object" } asks for any valid JSON object; { type: "json_schema" } additionally pins the shape.

curl https://boldrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $BOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      { "role": "user", "content": "Extract the name and age: Ada is 36." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer" }
          },
          "required": ["name", "age"]
        }
      }
    }
  }'

Provider support

Support differs by provider, so the gateway resolves the parameter against whichever provider serves the request:

Reasoning control

Tune how much a reasoning model thinks with the reasoning object. The gateway translates it into each provider's own parameters, such as Anthropic effort, OpenAI reasoning_effort or a Gemini thinking budget. Models without reasoning ignore it.

curl https://boldrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $BOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "messages": [{ "role": "user", "content": "Plan a database migration." }],
    "reasoning": { "effort": "high" }
  }'

Use "reasoning": { "enabled": false } to turn thinking off. Some models always think, and there the gateway uses the lightest setting the provider allows instead:

• Lowest effort instead of off: OpenAI reasoning models, Grok mini models, Kimi K3 and GLM-5.3.
• Always on, effort still applies: Claude Fable 5 and Mythos 5. Send "effort": "low" for the lightest thinking.
• No control at all: Kimi K2.7 Code, MiniMax M2.7, Arcee Trinity Large Thinking and gpt-oss.

Fallback chains

Provide a models array to define your own fallback order. If the primary model and all its providers fail, the gateway walks the chain - across providers and models - before giving up. This composes with the automatic provider failover (Routing & failover).

{
  "model": "openai/gpt-5.5",
  "models": ["anthropic/claude-opus-4.8", "google/gemini-2.5-pro"],
  "messages": [{ "role": "user", "content": "..." }]
}

Tool calling & multimodal

Pass OpenAI-shaped tools and image content parts; the gateway translates them to each provider's native format and normalizes tool-call deltas and stop reasons back to OpenAI's shape. Vision is supported on models whose catalog entry lists the vision capability.

Two boldrouter extensions ride on the same request: attach documents (PDF, Word, Excel, …) with a file content part - File & document input - and redact PII before it leaves the gateway with anonymize - Prompt anonymization.