API reference

Every request authenticates with your ub-gw-… key as a bearer token. Model ids are author/model slugs — browse the live, always-current set at /models rather than hard-coding one from a sample.

POST https://api.unoblox.ai/v1/chat/completions
Authorization: Bearer ub-gw-user_xxx-xxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: 6f0e-...        # optional; identifies this exact request — see Idempotency below

The core endpoint, accepting the OpenAI Chat Completions schema. The model is a unoblox slug (author/model) or a router alias.

POST /v1/chat/completions
{
  "model": "<model-id>",
  "messages": [
    { "role": "system", "content": "You are concise." },
    { "role": "user", "content": "Summarize GST in one line." }
  ],
  "temperature": 0.7,
  "max_tokens": 256,
  "stream": false
}

unoblox extensions (all optional):

Routing extensions are documented in Routing. They are consumed by the gateway and stripped before the upstream call.

Fields that change what the provider charges:

unoblox only forwards a request field that changes the provider's price when that price is on our price list, so you are always billed exactly what the provider charges (plus our 5% fee) and never something we cannot price. A field we cannot price is not sent to the provider; the request is still answered normally, and the response lists the field in the x-unoblox-unsupported-fields header.

If a stream ends early (you cancel it, or the provider fails mid-way), you are billed only what the provider charged for the work it did on that request — nothing if it charged nothing.

Response — the provider's completion, forwarded verbatim:

{
  "id": "chatcmpl-9f2a41",
  "object": "chat.completion",
  "created": 1756800000,
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "GST is India's unified indirect tax on goods and services." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 12, "total_tokens": 36 }
}

With stream: true the response is a text/event-stream of chat.completion.chunk frames ending in data: [DONE] — see Streaming.

The OpenAI Responses API shape, translated onto the same engine. Use instructions for the system prompt and input (a string or an item array) for the turn.

POST /v1/responses
{
  "model": "<model-id>",
  "instructions": "You are concise.",
  "input": "Summarize GST in one line.",
  "max_output_tokens": 256
}

Not accepted — each gets a 400 rather than being silently ignored: previous_response_id, conversation (unless null), store / background (unless false), context_management (unless an empty array), and an input item of type item_reference.

{
  "id": "resp_9f2a41",
  "object": "response",
  "created_at": 1756800000,
  "status": "completed",
  "model": "<model-id>",
  "output": [
    {
      "type": "message",
      "id": "msg_1",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "GST is …", "annotations": [] }]
    }
  ],
  "output_text": "GST is …",
  "usage": {
    "input_tokens": 24,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 12,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 36
  }
}

Streaming emits typed events in order: response.created → response.output_text.delta (repeated) → response.completed, each with an incrementing sequence_number.

The Anthropic Messages API shape. max_tokens is required (as in the Anthropic spec), and system is a top-level field. Authenticate with either Authorization: Bearer or x-api-key; the standard anthropic-version header is accepted and ignored (see Migration).

POST /v1/messages
{
  "model": "<model-id>",
  "max_tokens": 256,
  "system": "You are concise.",
  "messages": [{ "role": "user", "content": "Summarize GST in one line." }]
}

Not accepted — each gets a 400 rather than being silently ignored: context_management, container, service_tier, speed, and metadata.

{
  "id": "msg_9f2a41",
  "type": "message",
  "role": "assistant",
  "model": "<model-id>",
  "content": [{ "type": "text", "text": "GST is …" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Streaming emits Anthropic events: message_start → content_block_delta (repeated) → message_delta → message_stop.

The live catalog, in OpenAI list form. This endpoint is unauthenticated and returns the same list to everyone — it is not filtered by any key’s model_scope. Full field reference is in Models.

GET /v1/models  →
{
  "object": "list",
  "data": [
    { "id": "<model-id>", "object": "model", "owned_by": "<author>", "name": "<Model name>", "context_length": 128000, "freemium": false }
  ]
}

Four additional surfaces beyond chat/responses/messages, each gated by its own admin-configured enable flag — when disabled, every route below answers 503 provider_unavailable rather than 404, so a caller can tell “not enabled here” from “doesn’t exist”.

Embeddings and rerank are temporarily offline while their models are re-provisioned — routes below still answer 503 provider_unavailable. Batches and files are unaffected.

Optionally identify your application so it appears in public rankings and per-app usage analytics. At most one name source is used per request:

If your application identifies itself with the x-title or HTTP-Referer request headers, unoblox may show that application’s name and its aggregate usage by model in public rankings. unoblox never publishes usage by individual user, workspace or API key. To stay out of public rankings, do not send these headers.

Every inference response carries diagnostic headers:

Every failure returns a typed JSON envelope and a standard HTTP status. Branch on the type string:

{ "error": { "message": "…", "type": "insufficient_balance", "code": 402, "request_id": "7b679c45-…", "error_code": "UB-GW-…" } }

The full taxonomy — every type, its status, and whether to retry — is in Errors.

A separate API behind the dashboard — not the inference host above. It is reached through the web app itself, at https://unoblox.ai/api/webapi and https://unoblox.ai/api/identity, and (with one exception below) authenticates with the dashboard’s ubs_… session cookie, not your inference key.

On webapi:

A second exception to the session-cookie rule above: credits/balance, usage/activity/export and analytics/query/meta also accept a ub-mgmt-… management-scope API key as a bearer token, scoped to its own workspace only — see the Analytics API.

On identity:

GET /key (identity) is the one exception: an inference key introspects its own limits and scope, authenticated by the key itself (as a bearer token), not the session cookie.

GET /models and GET /providers on webapi are session-gated catalog mirrors for the dashboard — not the public catalog. The actual anonymous, read-only catalog is a distinct set of routes: GET /public/models, GET /public/models/:slug, GET /public/providers, and GET /public/site-config — what /models and /providers themselves call.