API reference

Conventions#

• These docs write the base URL as $INFERIQ_BASE_URL, which ends in /v1.
• Authenticate with Authorization: Bearer iq_…. The x-api-key header works too.
• Each key may use only the models chosen when it was created. /v1/models lists just those, and a request for any other model fails with model_not_allowed (403).
• Send JSON with Content-Type: application/json.
• Chat responses include x-inferiq-request-id, x-inferiq-receipt-id and x-inferiq-model. Include the request ID when you report a problem.
• Errors share one envelope with a stable code. See Errors.

Endpoints#

Endpoints marked with a phase are the planned contract and may change before they ship.

Chat completions#

POST /v1/chat/completions sends a conversation to a model and returns one completion, or a stream of chunks.

1234567891011curl $INFERIQ_BASE_URL/chat/completions \
  -H "Authorization: Bearer $INFERIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inferiq/balanced",
    "messages": [
      {"role": "system", "content": "You are a concise coding assistant."},
      {"role": "user", "content": "Why does Array.prototype.map return undefined items?"}
    ],
    "max_tokens": 400
  }'

Request fields#

model

Required. An alias (inferiq/fast, inferiq/balanced, inferiq/best) or an exact model id from /v1/models. It must be one this key may use, or the request fails with model_not_allowed.

messages

Required. Roles system, developer, user, assistant and tool. Text and image content parts; assistant tool_calls and tool results.

stream

Optional. true for server-sent events.

stream_options.include_usage

Optional. true to receive a final usage-only chunk.

max_tokens · max_completion_tokens

Optional. Upper bound on output tokens. Also sets the worst case your balance must cover.

tools · tool_choice · parallel_tool_calls

Optional. Function tools, passed to the model as-is.

temperature · top_p · stop

Optional. Passed through.

reasoning_effort

Optional. low, medium or xhigh. Without it, the alias’s level applies: fast low, balanced medium, best xhigh.

routing.fallback

Optional, Inferiq. Default true. false stays on the first candidate.

routing.allowed_models

Optional, Inferiq. Narrows an alias to these model ids.

Response#

HTTP/1.1 200 OK
content-type: application/json
x-inferiq-request-id: req_QXt5TzjNYPURUd0
x-inferiq-receipt-id: rcpt_QXt5TzjNYPURUd0
x-inferiq-model: qwen/qwen3.8-27b

1234567891011121314151617181920212223{
  "id": "chatcmpl-msg_01H8x…",
  "object": "chat.completion",
  "created": 1792160000,
  "model": "qwen/qwen3.8-27b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "map always returns an array of the same length. If your callback has no return…",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 118,
    "total_tokens": 170,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

model

The model that actually answered, e.g. qwen/qwen3.8-27b when you sent inferiq/balanced.

usage.prompt_tokens

All prompt tokens, each billed at the input price.

usage.completion_tokens

Output tokens, including the model’s reasoning before the answer.

x-inferiq-receipt-id

Look up the cost of this request at /v1/receipts/{id}.

Streaming#

With stream: true you get standard chat-completion chunks over server-sent events, ending with data: [DONE]. Tool call arguments arrive in pieces, keyed by index, exactly as OpenAI clients expect.

123456789data: {"id":"chatcmpl-msg_01H8x…","object":"chat.completion.chunk","model":"qwen/qwen3.8-27b","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-msg_01H8x…","object":"chat.completion.chunk","model":"qwen/qwen3.8-27b","choices":[{"index":0,"delta":{"content":"map always returns"},"finish_reason":null}]}

data: {"id":"chatcmpl-msg_01H8x…","object":"chat.completion.chunk","model":"qwen/qwen3.8-27b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-msg_01H8x…","object":"chat.completion.chunk","model":"qwen/qwen3.8-27b","choices":[],"usage":{"prompt_tokens":52,"completion_tokens":118,"total_tokens":170}}

data: [DONE]

Fallback happens before the first chunk. If a provider fails after tokens have started, the stream ends with an error event and no [DONE]:

data: {"error":{"message":"The provider failed mid-response.","type":"api_error","code":"provider_unavailable","retryable":true,"request_id":"req_QXt5TzjNYPURUd0"}}

Closing the connection stops the provider request too. You pay for what was generated up to that point.

Receipts#

GET /v1/receipts/{id} returns one receipt; GET /v1/receipts lists them newest first with limit (1–100) and before (an ISO timestamp). Field by field in Balance & receipts.

Fix agents#

POST /v1/fix/quote prices a fix; POST /v1/fix/runs runs the quote, holding its maximum and charging the actual cost; GET /v1/fix/runs/{id} returns the result. They need a key with the fix scope. Requests, responses and streamed events in Fix agents.

Compatibility#

The OpenAI Python and TypeScript SDKs work with only a new base URL and key; the gateway’s test suite runs the official TypeScript SDK against it, streaming tool calls included. Other tools are covered in Connect your tool. Compatibility is tested feature by feature, not promised for every parameter of every provider.