Skip to contentKumoDocs
Sections
On this page
The gateway

API reference

Every operation of the Kumo gateway, generated from the published API description: the address, how it is authenticated, what the request carries and what comes back.

View as Markdown

This page is generated from the API description this build was compiled against, so it says what the gateway answers rather than what it was once documented to answer. Every member below is a member of the wire.

POST /v1/chat/completions

Method
POST
Path
/v1/chat/completions
Auth
Authorization: Bearer <key>
Operation
public.chat_completions.create

The OpenAI-compatible chat surface: send a conversation, get one completion back or a stream of chunks.

Create a chat completion.

Answers one Chat Completions request against a model of the published catalog, authenticated by a Kumo API key. It is this protocol served natively and not a translation of another: the request members, the response shape, the usage vocabulary and the error envelope are this protocol's own.

A stream=true request is answered as text/event-stream — chat.completion.chunk events, a usage chunk when stream_options.include_usage asks for one, then the terminal [DONE] frame; a refusal decided before the first event is answered as this protocol's ordinary JSON error, and a failure after it ends the stream without its terminal frame.

An output ceiling is OPTIONAL — max_tokens or max_completion_tokens, interchangeably — and a request stating neither is answered under this surface's published default of 32768 output tokens, which is the finite bound the reservation is taken against before the upstream call. Stating both with different values is refused rather than resolved by a precedence rule.

reasoning_effort is carried to the model ONLY on a route that has proven it forwards a reasoning parameter and is dropped otherwise; it never changes which channels the request is offered, and an answer whose request stated it says which happened in the X-Kumo-Reasoning response header (forwarded or dropped).

{
  "max_tokens": 128,
  "messages": [
    {
      "role": "user"
    }
  ],
  "model": "<model>"
}

The request carries:

memberwhat it is
max_completion_tokensinteger, optional — The output ceiling, in the current spelling.
max_tokensinteger, optional — The output ceiling, in the spelling long-established clients send.
messagesarray of ChatMessage, required — The conversation, in order.
modelstring, required — The model to answer with: a canonical name or an alias the published catalog carries.
ninteger, optional — How many completions to answer with.
presence_penaltynumber, optional — Presence penalty from -2 to 2 inclusive.
reasoning_effortstring, optional — Carried to the model ONLY on a route that has proven it forwards a reasoning parameter, and dropped otherwise, with the X-Kumo-Reasoning response header saying which (forwarded or dropped).
response_formatChatResponseFormat, optional — A structured output requirement.
stoparray of string, optional — Sequences whose appearance ends the answer, at most four, as a LIST — the bare-string spelling this protocol also defines is not accepted on this surface and is refused rather than ignored.
streamboolean, optional — Whether to stream the answer.
stream_optionsChatStreamOptions, optional — Options that apply only when stream is true.
systemstring or array of ChatContentPart, optional — A system prompt beside the conversation, as OpenAI-compatible agents sometimes spell it.
temperaturenumber, optional — How much randomness to use, from 0 to 2 — this protocol's own interval, and not the [0, 1] of the Anthropic Messages surface.
tool_choice"auto" or "none" or "required" or object, optional — What this request requires of its tool list, in either spelling this protocol defines: the bare mode word "auto", "none" or "required", or an object naming one declared tool.
toolsarray of ChatTool, optional — The tools this turn may call.
top_pnumber, optional — Nucleus sampling, from 0 to 1.
userstring, optional — An opaque label for the end user this request is made on behalf of, as OpenAI-compatible clients send it.

ChatMessage

memberwhat it is
cache_controlChatCacheControl, optional — Accepted and NOT CARRIED: this marks the turn as a prompt-cache anchor, the way OpenAI-compatible clients write it when they address an Anthropic model, but the supplier wire this protocol is served by has no member for an anchor, so the cached-token counts in usage come back as though it had not been sent.
contentstring or array of ChatContentPart, optional — The turn's text, in either spelling this protocol defines: a bare string, or a list of typed parts joined in order.
namestring, optional — The tool this result came from, as OpenAI-compatible clients write it on a tool turn.
reasoningstring, optional — Accepted and NOT CARRIED: a prior assistant answer's reasoning, replayed by an OpenAI-compatible client.
reasoning_contentstring, optional — Accepted and NOT CARRIED: the alternate spelling of a prior assistant answer's replayed reasoning.
role"system" or "developer" or "user" or "assistant" or "tool", required — Who is speaking.
tool_call_idstring, optional — The call this result answers.
tool_callsarray of ChatToolCall, optional — The calls this assistant turn made, replayed back into the conversation so that a tool result has something in the history to answer.

ChatResponseFormat

memberwhat it is
json_schemaStructuredSchema, optional — The named schema an answer must satisfy.
typestring, required — The kind of format.

ChatStreamOptions

memberwhat it is
include_usageboolean, optional — Whether the stream ends with a usage chunk — an event with an empty choices array carrying only usage — before the terminal [DONE] frame.

ChatContentPart

memberwhat it is
cache_controlChatCacheControl, optional — Accepted and NOT CARRIED: this marks the part as a prompt-cache anchor, the way OpenAI-compatible clients write it when they address an Anthropic model, but the supplier wire this protocol is served by has no member for an anchor, so the cached-token counts in usage come back as though it had not been sent.
fileChatContentPartFile, optional — Declared and NEVER SERVED: the document a file part carries.
image_urlChatContentPartImage, optional — The image carried by an image_url part.
input_audioChatContentPartAudio, optional — Declared and NEVER SERVED: the sound an input_audio part carries.
refusalstring, optional — Declared and NEVER SERVED: the model's own refusal, replayed.
textstring, optional — On a text part, the text.
type"text" or "image_url" or "input_audio" or "file" or "refusal", required — Which kind of part this is.

ChatTool

memberwhat it is
functionChatToolFunction, required
type"function", required — The kind of tool.

The answer:

application/jsonChatCompletionsReply
text/event-streamChatCompletionsChunk
on failureChatCompletionsError

ChatCompletionsReply

memberwhat it is
choicesarray of ReplyChoice, required — The answer.
createdinteger, required — The instant this completion was answered, as whole seconds since the Unix epoch.
idstring, required — This request's Kumo identity.
modelstring, required — The model this request named, echoed back exactly as it was sent.
object"chat.completion", required — The kind of object this is.
usageReplyUsage, optional — What the supplier reported this request consumed.

ReplyChoice

memberwhat it is
finish_reason"stop" or "length" or "tool_calls" or "content_filter", required — Why the model stopped.
indexinteger, required — The position of this choice.
messageReplyMessage, required

ReplyUsage

memberwhat it is
completion_tokensinteger, optional — Output tokens the supplier counted.
prompt_tokensinteger, optional — Input tokens the supplier counted, including any it served from its own cache.
prompt_tokens_detailsPromptTokensDetails, optional — How the input divides, when the supplier said.
total_tokensinteger, optional — Input and output together.

ChatCompletionsChunk

memberwhat it is
choicesarray of ChunkChoice, required — This chunk's delta.
createdinteger, required — The instant this completion was answered, as whole seconds since the Unix epoch.
idstring, required — This request's Kumo identity, identical on every chunk of one stream.
modelstring, required — The model this request named, echoed back exactly as it was sent, on every chunk.
object"chat.completion.chunk", required — The kind of object this is.
usageReplyUsage, optional — Present only on the usage chunk — the last event before [DONE] when stream_options.include_usage asked for one — and absent from every content chunk.

ChunkChoice

memberwhat it is
deltaChunkDelta, required
finish_reason"stop" or "length" or "tool_calls" or "content_filter" or null, required — Why the model stopped, stated once on the chunk that closes the answer and null until then.
indexinteger, required — The position of this choice.

ReplyUsage

ReplyUsage — see above.

ChatCompletionsError

memberwhat it is
errorChatCompletionsErrorBody, required

ChatCompletionsErrorBody

memberwhat it is
codestring, optional — The machine-readable reason.
limitRequestLimit, optional — On a request_limit_exceeded refusal, which limit the request exceeded, the limit and the value the request reached; param names the member.
messagestring, required — What went wrong, in a fixed safe sentence.
paramstring, optional — The request member at fault, when one member is at fault.
probestring, optional — On a connect-check refusal only (a model named kumo-connect-check-<32 hex> that no live model answers to, asked with a valid key): kumo-connect-check-<nonce>:<proof>, where proof is the first 16 hex characters of HMAC-SHA256 over the nonce and the key id under a gateway-held key.
reason"welcome_model_cap" or "welcome_spent" or "welcome_photos_spent" or "daily_model_limit" or "daily_common_limit" or "daily_usage_limit" or "native_search" or "no_free_allowance" or "input_too_large" or "request_unbounded" or "not_eligible" or "free_variant_unavailable" or "limits_changed" or "free_limits_exhausted" or "requests_per_minute" or "concurrency", optional — On a free_limit_exhausted or free_rate_limited refusal only — a request that named a free variant (<model>:free) or the alias kumo/free, which is never paid: why it was refused, in a closed vocabulary.
reset_atstring, optional — On a free_limit_exhausted or free_rate_limited refusal, the instant the limit resets, when one exists: the next 00:00 Europe/Moscow for a daily free limit (and for an account whose daily free limits open then), the end of the counted minute for the per-minute limit.
type"invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "rate_limit_error" or "api_error", required — The class of failure, in this protocol's own closed vocabulary.

POST /v1/embeddings

Method
POST
Path
/v1/embeddings
Auth
Authorization: Bearer <key>
Operation
public.embeddings.create

Turn a batch of inputs into vectors, one vector per input.

Create embedding vectors for a batch of inputs.

Returns one vector per input, in the order the inputs were given. Billing counts input tokens only: this surface produces no output tokens and no image units, and the ledger records zero for both.

The batch is bounded — at most 128 inputs and 131072 bytes in total — and a request outside those bounds is refused before any provider is called. Streaming is not part of this surface. encoding_format must be stated and must be "base64": vectors are returned as base64-encoded little-endian float32, and this surface does not serve this protocol's "float" default.

A request asking for float, or asking for nothing and therefore for float, is refused by name rather than answered in another format.

{
  "encoding_format": "base64",
  "input": [
    "<input>"
  ],
  "model": "<model>"
}

The request carries:

memberwhat it is
encoding_format"base64", required — Must be "base64": this surface does not serve the protocol's "float" default.
inputarray of string, required — The batch of inputs to embed, at most 128 members and 131072 bytes in total.
modelstring, required — The catalog model to embed with, as the customer names it.

The answer:

application/jsonEmbeddingsResponseBody
on failureEmbeddingsError

EmbeddingsResponseBody

memberwhat it is
dataarray of EmbeddingsVector, required — One vector per input, in the order the inputs were given.
modelstring, required — The model the vectors were produced with.
object"list", required — Always "list".
usageEmbeddingsUsage, required — What the request cost.

EmbeddingsVector

memberwhat it is
embeddingstring, required — The vector components as base64-encoded little-endian float32 values, which is this protocol's own "base64" encoding format.
indexinteger, required — The position of the input this vector is for.
object"embedding", required — Always "embedding".

EmbeddingsUsage

memberwhat it is
prompt_tokensinteger, required — The input tokens charged for this request.
total_tokensinteger, required — The total tokens charged, which on this surface equals prompt_tokens.

EmbeddingsError

memberwhat it is
errorEmbeddingsErrorBody, required — The failure.

EmbeddingsErrorBody

memberwhat it is
codestring, required — The machine-readable reason, shared with every Kumo surface.
messagestring, required — A safe description of the failure.
request_idstring, optional — The Kumo request identifier, for support.
typestring, required — The class of failure.

GET /v1/free/limits

Method
GET
Path
/v1/free/limits
Auth
Authorization: Bearer <key>
Operation
public.free_limits.read

Read the free limits of the API key's account: for each free model, what is left and when it resets.

Read the free limits of the API key's organization.

For a Kumo API key: every free model the key may use by the ID of its free variant (<canonical>:free), with the level that funds a request of it now (welcome — the Welcome package; daily — the daily free limits of an account with a qualifying purchased package; none), its limit, what is used and what is left in the model's own tokens (images for the Welcome photo model), and reset_at — the next 00:00 Europe/Moscow where a daily limit resets or opens.

rate states the two rate limits of free usage, per organization: requests per UTC minute — every request that names a free variant counts, also one refused for an exhausted free limit, so retrying an exhausted limit spends the minute — and requests in flight. The figures may be up to one second old.

They are the ones a request's own answer states: the x-ratelimit-* and x-free-* headers of every answer to a request that names a free variant, and the reason and reset_at of its 429.

A request that names a free variant is never paid: past its free limits it answers 429 free_limit_exhausted, past the rate limits 429 free_rate_limited; the plain model ID is the paid one. The read itself counts nothing. router names the «any free model» alias (kumo/free) while a free text model is listed.

{
  "active": true,
  "models": [
    {
      "base_model": "<base_model>",
      "left": 1,
      "level": "welcome",
      "limit": 1,
      "model": "<model>",
      "reset_at": "<reset_at>",
      "unit": "tokens",
      "used": 1
    }
  ],
  "object": "free_limits",
  "rate": {
    "concurrency": {
      "in_flight": 1,
      "limit": 1
    },
    "requests_per_minute": {
      "left": 1,
      "limit": 1,
      "reset_at": "<reset_at>"
    }
  }
}

The request carries no body.

The answer:

application/jsonFreeLimitsBody
on failureErrorEnvelope

FreeLimitsBody

memberwhat it is
activeboolean, required — Whether the organization has free variants at all: the promotion is on and released to it.
modelsarray of FreeLimitsModel, required — Every free model the key may use, by canonical name.
object"free_limits", required
rateFreeLimitsRate, required — The rate limits of free usage, shared by every free model; past either a request answers 429 free_rate_limited.
routerstring, optional — The model ID of the «any free model» alias, kumo/free, while at least one free text model is listed: a request that names it is routed to the first listed text model with remaining allowance and a free channel, and behaves as that model's :free.

FreeLimitsModel

memberwhat it is
base_modelstring, required — The model's canonical name — the ID of the paid model.
expires_atstring, optional — On the welcome level, when the Welcome package ends.
leftinteger, required — What a request can still take: the model's own remainder, never more than its level's other bound leaves (the Welcome package's total, the common daily limit); 0 at level none.
level"welcome" or "daily" or "none", required — The level a request of the free variant is funded from now.
limitinteger, required — The model's limit on its level — on the daily level never above the account's common daily limit; 0 at level none.
modelstring, required — The model ID that uses the model for free: the canonical name with the suffix :free.
requestsFreeLimitsRequests, optional — On the daily level, the model's free requests per Moscow day.
reset_atstring, required — When the allowance resets: the next 00:00 Europe/Moscow on the daily level, and at level none for an account whose daily free limits open then (a qualifying purchased package, its Welcome finished today).
unit"tokens" or "images", required — What limit, used and remaining count: the model's own tokens (uncached input, cache read, cache write and output, summed; no multiplier), or images for the Welcome photo model.
usedinteger, required — What admission counts as taken, requests in flight included; 0 at level none.

FreeLimitsRate

memberwhat it is
concurrencyFreeLimitsConcurrency, required
requests_per_minuteFreeLimitsWindow, required

ErrorEnvelope

memberwhat it is
errorErrorBody, required — The envelope payload.

ErrorBody

memberwhat it is
codestring, required — Machine-readable error code.
field_detailsarray of FieldDetail, optional — Per-field rejections, when the error is a validation error.
limitLimitDetail, optional — Present when the error is a limit or funding-source rejection.
messagestring, required — Safe human-readable fallback.
promotionPromotionDetail, optional — Present when the error is a named promotion refusal.
request_idstring, required — Matches the X-Request-Id response header.
versionstring, required — Envelope version.

POST /v1/images/edits

Method
POST
Path
/v1/images/edits
Auth
Authorization: Bearer <key>
Operation
public.images.edit

Edit images with a prompt and up to four uploaded PNG or JPEG files.

Edit images from a prompt and source files.

Edits up to four PNG or JPEG source files using a model with a verified editing route. Use multipart/form-data and repeat either image or image[] for multiple files. Edits use the Images API response and error formats. Billing is per returned image.

{
  "model": "<model>",
  "prompt": "<prompt>"
}

The request carries:

memberwhat it is
imagearray of string, optional — Source files, in order.
image[]array of string, optional — Alternative spelling of image for OpenAI-style clients.
modelstring, required
ninteger, optional — How many images to generate.
promptstring, required
response_format"b64_json", optional
sizestring, optional

The answer:

application/jsonImagesResponseBody
on failureImagesErrorBody

ImagesResponseBody

memberwhat it is
createdinteger, required — When the images were generated, as a Unix timestamp in seconds.
dataarray of ImagesDataEntry, required — The generated images, in the order the supplier answered them.

ImagesDataEntry

memberwhat it is
b64_jsonstring, optional — The image bytes, base64-encoded.
urlstring, optional — A URL the image can be fetched from.

ImagesErrorBody

memberwhat it is
errorImagesErrorPayload, required — The refusal, in the OpenAI-compatible error shape.

ImagesErrorPayload

memberwhat it is
codestring, required — The machine-readable reason.
messagestring, required — A safe human-readable description of the refusal.
paramstring, required — Always null: this surface never names a field of the request.
reason"welcome_model_cap" or "welcome_spent" or "welcome_photos_spent" or "daily_model_limit" or "daily_common_limit" or "daily_usage_limit" or "native_search" or "no_free_allowance" or "input_too_large" or "request_unbounded" or "not_eligible" or "free_variant_unavailable" or "limits_changed" or "free_limits_exhausted" or "requests_per_minute" or "concurrency", optional — On a free_limit_exhausted or free_rate_limited refusal only — a request that named a free variant (<model>:free) or the alias kumo/free, which is never paid: why it was refused, in a closed vocabulary.
reset_atstring, optional — On a free_limit_exhausted or free_rate_limited refusal, the instant the limit resets, when one exists: the next 00:00 Europe/Moscow for a daily free limit (and for an account whose daily free limits open then), the end of the counted minute for the per-minute limit.
typestring, required — The coarse OpenAI error class.

POST /v1/images/generations

Method
POST
Path
/v1/images/generations
Auth
Authorization: Bearer <key>
Operation
public.images.generate

Generate one or more images from a text prompt.

Generate images from a prompt.

Generates one or more images from a text prompt with an image-capable model. The request and response envelopes are OpenAI-compatible, and so is the error envelope: refusals carry error.message, error.type and error.code rather than Kumo's REST envelope. Billing is per image unit, debited through the same admission, reservation and settlement kernel as every other model surface.

An explicit response_format is honored. Other OpenAI optional members are accepted and validated but not applied. Image edits are served separately; variations are not served.

{
  "model": "<model>",
  "prompt": "<prompt>"
}

The request carries:

memberwhat it is
backgroundstring, optional — Accepted for OpenAI compatibility and not applied.
modelstring, required — The public model name to generate with.
moderationstring, optional — Accepted for OpenAI compatibility and not applied.
ninteger, optional — How many images to generate.
output_compressioninteger, optional — Accepted for OpenAI compatibility and not applied.
output_formatstring, optional — Accepted for OpenAI compatibility and not applied.
promptstring, required — The prompt to generate an image from.
qualitystring, optional — Accepted for OpenAI compatibility and not applied.
response_formatstring, optional — Requested image representation: url or b64_json.
sizestring, optional — The image size as WIDTHxHEIGHT, for example 1024x1024.
stylestring, optional — Accepted for OpenAI compatibility and not applied.
userstring, optional — Accepted for OpenAI compatibility, never forwarded to a supplier and never stored.

The answer:

application/jsonImagesResponseBody
on failureImagesErrorBody

ImagesResponseBody

ImagesResponseBody — see above.

ImagesDataEntry

ImagesDataEntry — see above.

ImagesErrorBody

ImagesErrorBody — see above.

ImagesErrorPayload

ImagesErrorPayload — see above.

POST /v1/messages

Method
POST
Path
/v1/messages
Auth
Authorization: Bearer <key> or x-api-key: <key>
Operation
public.anthropic_messages.create

The Anthropic Messages surface: send a conversation in that protocol's own shape, get one message back or a stream of events.

Create a message.

Answers one Anthropic Messages request against a model of the published catalog, authenticated by a Kumo API key.

It is this protocol served NATIVELY and not a translation of another: max_tokens is required and has no default, the system prompt is a member of the request rather than a turn of the conversation, tools carry input_schema with no function wrapper, the answer states stop_reason and content blocks, and refusals arrive in this protocol's own error envelope.

A tool exchange is carried natively — an assistant's calls as tool_use blocks with input as the JSON object the tool schema describes, and their results as tool_result blocks of the following user turn.

A stream=true request is answered as text/event-stream carrying this protocol's own named events — message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop — with a refusal decided before the first event answered as this protocol's ordinary JSON error, and a failure after it expressed in-stream as this protocol's error event, the stream then ending without message_stop.

The credential may be presented as Authorization: Bearer <key> or, as the native API does it, bare in the x-api-key header; either admits the caller. When both are present the Authorization header is the one read and the bare header is ignored. Sampling is carried to the supplier unchanged: temperature, top_p and stop_sequences.

Three members are ACCEPTED AND HAVE NO EFFECT, and each says so in its own description rather than being refused or silently honoured — metadata, which this platform does not forward because it would describe a customer's own user to a supplier, context_management, because this platform holds no server-side context to manage, and safeguards, which this platform does not forward because it describes the caller's machine.

The two reasoning members, thinking and output_config.effort, are conditional: each is carried to the model ONLY on a route that has proven it forwards a reasoning parameter and is dropped otherwise; neither changes which channels the request is offered, and an answer whose request stated one says which happened in the X-Kumo-Reasoning response header (forwarded or dropped).

A prompt-cache anchor, cache_control, is carried to the supplier, and its ttl is ACCEPTED AND NOT FORWARDED: the anchor lives the protocol's default five minutes whichever life is stated, and the request is settled at that lifetime; the answer's usage therefore states cache_creation with every written token in its five-minute bucket.

The anthropic-beta request header is read and only a short list of money-neutral values is forwarded, on routes served by Anthropic's own API; any other value is not forwarded. A request the wallet or package cannot fund is refused 402 with the error type billing_error.

{
  "max_tokens": 128,
  "messages": [
    {
      "content": "<content>",
      "role": "user"
    }
  ],
  "model": "<model>"
}

The request carries:

memberwhat it is
context_managementobject, optional — This protocol's context-management configuration, as the beta spells it.
max_tokensinteger, required — The maximum number of tokens to generate.
messagesarray of MessagesInputMessage, required — The conversation, oldest turn first.
metadataMessagesMetadata, optional — This protocol's request metadata.
modelstring, required — The catalog model to answer with, as the customer names it.
output_configobject, optional — Its effort member is carried to the model ONLY on a route that has proven it forwards a reasoning parameter, and dropped otherwise, with the X-Kumo-Reasoning response header saying which (forwarded or dropped).
safeguardsarray of object, optional — ACCEPTED and NOT forwarded: the context a client states for its own permission classifier, as the dangerous-tool-use beta spells it (Claude Code sends it in auto mode).
stop_sequencesarray of string, optional — Sequences that end the answer when the model produces one.
streamboolean, optional — Stream the answer as this protocol's own named events over text/event-stream: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop.
systemstring or array of MessagesSystemBlock, optional — The system prompt, beside the conversation rather than as a turn of it.
temperaturenumber, optional — How much randomness to use, from 0 to 1.
thinkingobject, optional — Carried to the model ONLY on a route that has proven it forwards a reasoning parameter, and dropped otherwise, with the X-Kumo-Reasoning response header saying which (forwarded or dropped).
tool_choiceMessagesToolChoice, optional — Forces one of the declared tools.
toolsarray of MessagesTool, optional — The tools this turn may call.
top_kinteger, optional — Keep only the K most likely tokens when sampling.
top_pnumber, optional — Nucleus sampling, from 0 to 1.

MessagesInputMessage

memberwhat it is
contentstring or array of MessagesContentBlock, required — What the turn says.
output_configobject, optional — The beta's per-turn output configuration, as the client states it on a turn — an effort level, a timing.
role"user" or "assistant" or "system", required — Who is speaking.

MessagesMetadata

memberwhat it is
user_idstring, optional — An opaque identifier the caller keeps for its own end user.

MessagesSystemBlock

memberwhat it is
cache_controlMessagesCacheControl, optional — Marks this block as a prompt-cache anchor.
textstring, required — The block's text.
type"text", required — Always "text".

MessagesToolChoice

memberwhat it is
disable_parallel_tool_useboolean, optional — Whether at most one tool may be called in one answer; the default is that several may be.
namestring, optional — The tool to force.
type"auto" or "any" or "tool" or "none", required — What the request requires: "auto" leaves the choice to the model, "any" requires a call to some declared tool, "tool" requires a call to the one "name" states, and "none" forbids a call while the declarations stay visible.

MessagesTool

memberwhat it is
allowed_callersarray of string, optional — The beta's list of tools permitted to call this one.
allowed_domainsarray of string, optional — On a hosted search, the allowed domains; mutually exclusive with blocked_domains.
blocked_domainsarray of string, optional — On a hosted search, the blocked domains; mutually exclusive with allowed_domains.
cache_controlMessagesCacheControl, optional — Marks this declaration as a prompt-cache anchor; the tool list is part of the cached prefix.
defer_loadingboolean, optional — The beta's request to load this declaration only when it is first needed.
descriptionstring, optional — What the tool does.
eager_input_streamingboolean, optional — The beta's request to begin streaming this tool's arguments before they are complete.
input_examplesarray of object, optional — The beta's example arguments for this tool, each the JSON object input_schema describes.
input_schemaobject, optional — The tool's parameters, as the JSON Schema the caller wrote for its own tool.
max_usesinteger, optional — On native web search, the maximum number of searches in this request, relayed to the supplier and reserved before execution.
namestring, required — The tool's name.
strictboolean, optional — The beta's request that the arguments conform exactly to input_schema.
typestring, optional — The declaration kind: absent or custom is a caller tool; web_search_20250305 is supplier-hosted web search, relayed natively.
user_locationMessagesSearchLocation, optional — On a hosted search, its approximate search location.

The answer:

application/jsonMessagesReply
text/event-streamMessagesStreamEvent
on failureMessagesError

MessagesReply

memberwhat it is
contentarray of MessagesReplyBlock, required — The answer's blocks, in order.
idstring, required — The Kumo request identifier for this answer.
modelstring, required — The model the customer named.
rolestring, required — Always "assistant".
stop_reason"end_turn" or "max_tokens" or "stop_sequence" or "tool_use" or "pause_turn", required — Why the answer ended.
typestring, required — Always "message".
usageMessagesReplyUsage, optional — What the request cost, exactly as this platform settles it.

MessagesReplyBlock

memberwhat it is
citationsarray of MessagesWebCitation, optional — On a text block, native web-search citations.
contentstring or array of MessagesToolResultBlock or object, optional — On a web_search_tool_result, the native result list or typed search error, preserved for replay.
datastring, optional — On a redacted_thinking block, the vendor's opaque data: thinking the vendor encrypted rather than showed.
idstring, optional — On a tool use, its identifier.
inputobject, optional — On a tool use, the arguments as the JSON object the supplier produced.
namestring, optional — On a tool use, the tool called.
signaturestring, optional — On a thinking block, the vendor's opaque signature of it.
textstring, optional — On a text block, the text.
thinkingstring, optional — On a thinking block, the model's thinking text; it may be the empty string.
tool_use_idstring, optional — On a web_search_tool_result, the server call it answers.
type"text" or "tool_use" or "thinking" or "redacted_thinking" or "server_tool_use" or "web_search_tool_result", required — Which kind of block this is.

MessagesReplyUsage

memberwhat it is
cache_creationMessagesCacheCreation, optional — The cache write by lifetime.
cache_creation_input_tokensinteger, required — Input tokens written to the prompt cache.
cache_read_input_tokensinteger, required — Input tokens served from the prompt cache.
input_tokensinteger, required — Input tokens charged, excluding cache reads and writes.
output_tokensinteger, required — Output tokens charged.
server_tool_useMessagesWebSearchUsage, optional — Supplier-reported server-tool usage, including successful web search calls.

MessagesStreamEvent

memberwhat it is
content_blockMessagesStreamBlock, optional — On content_block_start, the opening block.
deltaMessagesStreamDelta, optional — On content_block_delta, the fragment; on message_delta, the closing facts.
errorMessagesErrorBody, optional — On error, the failure, in this protocol's own envelope.
indexinteger, optional — On the block events, which block.
messageMessagesStreamMessage, optional — On message_start, the opening envelope: the answer's identity and the account's input half.
type"message_start" or "content_block_start" or "content_block_delta" or "content_block_stop" or "message_delta" or "message_stop" or "ping" or "error", required — Which event this is; it is also the SSE frame's event name.
usageMessagesReplyUsage, optional — On message_delta, what the request cost — exactly as this platform settles it, and exactly what the unary reply would state.

MessagesStreamBlock

memberwhat it is
citationsarray of MessagesWebCitation, optional — On a text opening, the native citations already present.
contentstring or array of MessagesToolResultBlock or object, optional — On a web_search_tool_result, its complete native results or typed error.
datastring, optional — On a redacted_thinking block, the vendor's opaque data, whole: this block has no fragments.
idstring, optional — On a tool use, its identifier.
inputobject, optional — On a tool use, the opening input — the empty object; the arguments arrive as input_json_delta fragments.
namestring, optional — On a tool use, the tool called.
signaturestring, optional — On a thinking block, the opening signature — ordinarily empty; the vendor's opaque signature arrives as a signature_delta fragment before the block closes.
textstring, optional — On a text block, the opening text — empty; the text arrives as deltas.
thinkingstring, optional — On a thinking block, the opening thinking text — ordinarily empty; the text arrives as thinking_delta fragments.
tool_use_idstring, optional — On a web_search_tool_result, the server call it answers.
type"text" or "tool_use" or "thinking" or "redacted_thinking" or "server_tool_use" or "web_search_tool_result", required — Which kind of block opened.

MessagesStreamDelta

memberwhat it is
citationMessagesWebCitation, optional — On citations_delta, the native web-search citation.
partial_jsonstring, optional — On input_json_delta, the fragment of the call's input object, as partial JSON text.
signaturestring, optional — On signature_delta, the vendor's opaque signature of the thinking block being streamed, or a fragment of it.
stop_reason"end_turn" or "max_tokens" or "stop_sequence" or "tool_use" or "pause_turn", optional — On message_delta, why the answer ended.
textstring, optional — On text_delta, the fragment of the answer's text.
thinkingstring, optional — On thinking_delta, the fragment of a thinking block's text.
type"text_delta" or "input_json_delta" or "thinking_delta" or "signature_delta" or "citations_delta", optional — On content_block_delta, which fragment this is; absent on message_delta.

MessagesErrorBody

memberwhat it is
codestring, optional — The machine-readable reason, shared with every Kumo surface.
limitRequestLimit, optional — On a request_limit_exceeded refusal, which limit the request exceeded, the limit and the value the request reached; param names the member.
messagestring, required — A safe description of the failure.
paramstring, optional — The member the failure is about, when it is about one.
probestring, optional — On a connect-check refusal only (a model named kumo-connect-check-<32 hex> that no live model answers to, asked with a valid key): kumo-connect-check-<nonce>:<proof>, where proof is the first 16 hex characters of HMAC-SHA256 over the nonce and the key id under a gateway-held key.
reason"welcome_model_cap" or "welcome_spent" or "welcome_photos_spent" or "daily_model_limit" or "daily_common_limit" or "daily_usage_limit" or "native_search" or "no_free_allowance" or "input_too_large" or "request_unbounded" or "not_eligible" or "free_variant_unavailable" or "limits_changed" or "free_limits_exhausted" or "requests_per_minute" or "concurrency", optional — On a free_limit_exhausted or free_rate_limited refusal only — a request that named a free variant (<model>:free) or the alias kumo/free, which is never paid: why it was refused, in a closed vocabulary.
reset_atstring, optional — On a free_limit_exhausted or free_rate_limited refusal, the instant the limit resets, when one exists: the next 00:00 Europe/Moscow for a daily free limit (and for an account whose daily free limits open then), the end of the counted minute for the per-minute limit.
type"invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "billing_error" or "rate_limit_error" or "api_error" or "overloaded_error", required — The class of failure.

MessagesStreamMessage

memberwhat it is
contentarray of MessagesReplyBlock, required — Always empty here: the blocks arrive as events.
idstring, required — The Kumo request identifier for this answer, identical on every event of one stream.
modelstring, required — The model the customer named.
rolestring, required — Always "assistant".
typestring, required — Always "message".
usageMessagesReplyUsage, required — The account's input half, as the supplier stated it on opening; the closing message_delta states the settled whole.

MessagesReplyUsage

MessagesReplyUsage — see above.

MessagesError

memberwhat it is
errorMessagesErrorBody, required — The failure.
type"error", required — Always "error".

MessagesErrorBody

MessagesErrorBody — see above.

POST /v1/messages/count_tokens

Method
POST
Path
/v1/messages/count_tokens
Auth
Authorization: Bearer <key> or x-api-key: <key>
Operation
public.anthropic_messages.count_tokens

Count how many tokens a Messages request would spend, without spending them.

Count message input tokens.

Authenticates a Kumo API key and returns a deterministic local estimate for a subset of the native Messages input accepted by /v1/messages: model, messages, system, tools, tool_choice, thinking, metadata, context_management and safeguards. It performs no provider call, creates no customer request or reservation, touches no balance, and consumes no customer RPS/RPM quota.

The generation-only members are refused on this operation: max_tokens, stream, output_config, stop_sequences, temperature, top_p and top_k. The credential may be presented as Authorization: Bearer <key> or, as the native API does it, bare in the x-api-key header; either admits the caller. When both are present the Authorization header is the one read and the bare header is ignored.

{
  "messages": [
    {
      "content": "<content>",
      "role": "user"
    }
  ],
  "model": "<model>"
}

The request carries:

memberwhat it is
context_managementobject, optional — This protocol's context-management configuration, as the beta spells it.
messagesarray of MessagesInputMessage, required — The conversation, oldest turn first.
metadataMessagesMetadata, optional — This protocol's request metadata.
modelstring, required — The catalog model to answer with, as the customer names it.
safeguardsarray of object, optional — ACCEPTED and NOT forwarded: the context a client states for its own permission classifier, as the dangerous-tool-use beta spells it (Claude Code sends it in auto mode).
systemstring or array of MessagesSystemBlock, optional — The system prompt, beside the conversation rather than as a turn of it.
thinkingobject, optional — Carried to the model ONLY on a route that has proven it forwards a reasoning parameter, and dropped otherwise, with the X-Kumo-Reasoning response header saying which (forwarded or dropped).
tool_choiceMessagesToolChoice, optional — Forces one of the declared tools.
toolsarray of MessagesTool, optional — The tools this turn may call.

MessagesInputMessage

MessagesInputMessage — see above.

MessagesMetadata

MessagesMetadata — see above.

MessagesSystemBlock

MessagesSystemBlock — see above.

MessagesToolChoice

MessagesToolChoice — see above.

MessagesTool

MessagesTool — see above.

The answer:

application/jsonAnthropicTokenCountReply
on failureMessagesError

AnthropicTokenCountReply

memberwhat it is
estimatedboolean, required — Always true until an exact local tokenizer is available.
input_tokensinteger, required — The deterministic local estimate of input tokens.

MessagesError

MessagesError — see above.

MessagesErrorBody

MessagesErrorBody — see above.

GET /v1/models

Method
GET
Path
/v1/models
Auth
None — this operation is open.
Operation
public.models.list

List every model this gateway currently answers for.

List enabled, evidence-backed models.

Returns only active catalog models that have at least one enabled capability in the currently published provider configuration. Protocol and modality support are the exact intersection of catalog declarations and routable provider evidence; disabled or unproven tuples are absent.

Called with a valid Kumo API key (Authorization: Bearer or x-api-key), the list may hold only the models that key's model, provider and modality access settings admit (rolled out in stages), and such an answer is Cache-Control private; without a key, or with a key that does not authenticate, the full list is returned and nothing is refused.

Free variants: while a model is free, its free variant is the model ID <canonical>:free — only a request that names it spends the account's free limits, and it is never paid: when they are exhausted it answers 429 free_limit_exhausted with the reason and reset_at (429 free_rate_limited past the per-minute or in-flight limit of free usage); the plain ID is always paid.

A request that presents a valid Kumo API key gets, after each free model that key may use, a second row for the free variant (free_variant true, base_model the plain canonical name); a request without a key gets those rows only when it asks variants=free.

While a model is not free its :free ID is listed nowhere and a request to it is answered 404 model_not_found.

{
  "catalog_revision": 1,
  "data": [
    {
      "banner_seed": 1,
      "canonical_name": "<canonical_name>",
      "capabilities": [
        {
          "modality_code": "text_generation",
          "protocol_code": "responses",
          "status": "enabled",
          "streaming_status": "unsupported",
          "strict_semantics_status": "unsupported",
          "structured_output_mode": "none",
          "structured_output_status": "unsupported",
          "structured_output_streaming_status": "unsupported",
          "tools_status": "unsupported"
        }
      ],
      "description_en": "<description_en>",
      "description_ru": "<description_ru>",
      "display_name_en": "<display_name_en>",
      "display_name_ru": "<display_name_ru>",
      "id": "<id>",
      "modality_codes": [
        "text_generation"
      ],
      "model_id": "<model_id>",
      "object": "model",
      "protocol_codes": [
        "responses"
      ],
      "supplier_count": 1,
      "vendor": {
        "code": "<code>",
        "display_name_en": "<display_name_en>",
        "display_name_ru": "<display_name_ru>",
        "id": "<id>"
      }
    }
  ],
  "loaded_at": "<loaded_at>",
  "object": "list",
  "stale": true
}

The request carries no body.

The answer:

application/jsonPublicModelCatalog
on failureErrorEnvelope

PublicModelCatalog

memberwhat it is
catalog_revisioninteger, required — The append-only catalog revision.
dataarray of PublicCatalogModel, required
first_idstring, optional — Anthropic list shape: id of the first entry of data.
has_moreboolean, optional — Anthropic list shape: always false, the listing is never paged.
last_idstring, optional — Anthropic list shape: id of the last entry of data.
loaded_atstring, required
object"list", required
staleboolean, required — True only when a database refresh failed; the response then retains revision diagnostics but advertises no model capabilities.

PublicCatalogModel

memberwhat it is
added_onstring, optional — The UTC day this model was added to the Kumo catalogue, as yyyy-mm-dd.
aliasesarray of string, optional
banner_seedinteger, required — The seed of the model's halftone banner.
base_modelstring, optional — On a free-variant row, the canonical name of the model it is the free variant of — the id of the paid row beside it.
benchmarksCatalogBenchmarks, optional — The model's place on the benchmark leaderboards this platform publishes at /benchmarks: Artificial Analysis indices, speed, latency and cost per task with the rank among every measured model, its weekly place on OpenRouter and its best task categories.
canonical_namestring, required — The model's canonical name.
capabilitiesarray of ModelCapability, required
context_window_tokensinteger, optional — How many tokens this model accepts in one request.
created_atstring, optional — RFC 3339 instant of the model.
descriptionstring, optional — The model's one-line description as a client that discovers models through this list shows it.
description_enstring, required
description_rustring, required
display_namestring, optional — The model's name as a client that discovers models through this list labels it.
display_name_enstring, required
display_name_rustring, required
free_routerboolean, optional — True on the one row of the «any free model» alias, kumo/free, listed for an API key while its organization has at least one free text model the key may use.
free_variantboolean, optional — True on the row of a model's free variant: the model ID <canonical>:free.
header_badge"top" or "value" or "fast", optional — The card this model fills in the header models panel.
idstring, required — The name an API request names this model by — the canonical name, so an OpenAI-compatible client that lists models and sends back data[].id as model is answered.
image_inputboolean, optional — True when the model accepts photos (image_url parts): declared by the catalogue AND proven by a vision probe.
max_output_tokensinteger, optional — How many tokens this model may answer with in one call.
modality_codesarray of "text_generation" or "embeddings" or "image_generation" or "decisions", required
model_idstring, required — The catalog's UUID for this model, the key that pricing, key scopes and usage rows join on.
object"model", required
popularity_rankinteger, optional — The model's place in the catalogue's popularity order, 1 first.
protocol_codesarray of "responses" or "chat_completions" or "anthropic_messages" or "embeddings" or "images" or "decisions", required
reasoning_protocol_codesarray of "responses" or "chat_completions" or "anthropic_messages" or "embeddings" or "images" or "decisions", optional — The protocols, a subset of protocol_codes in the same order, on which a reasoning parameter (Messages thinking / output_config.effort, Chat Completions reasoning_effort, Responses reasoning) is forwarded to the supplier on this model's primary route.
released_onstring, optional — The day this model's maker released it, as yyyy-mm-dd.
showcase_positioninteger, optional — The model's place on the landing model carousel, ascending.
supplier_countinteger, required — Deprecated compatibility placeholder, always 1.
type"model", optional — Anthropic Models API discriminator, always model.
typical_requestCatalogTypicalRequest, optional — What one average request to this model actually spends, measured over the platform's own finished traffic.
vendorCatalogVendor, required

ErrorEnvelope

ErrorEnvelope — see above.

ErrorBody

ErrorBody — see above.

POST /v1/responses

Method
POST
Path
/v1/responses
Auth
Authorization: Bearer <key>
Operation
public.responses.create

The newer OpenAI Responses surface: send input items, get one response object back or a stream of events.

Create a response.

Answers one Responses request against a model of the published catalog, authenticated by a Kumo API key. It is this protocol served natively and not a translation of another: the input items, the output items, the usage vocabulary and the error envelope are this protocol's own.

A stream=true request is answered as text/event-stream in this protocol's own named events — response.created, the output items and their deltas, then exactly one terminal event: response.completed or response.incomplete carrying the finished body and usage, or response.failed carrying this protocol's error envelope.

A failure before the first event is answered as this protocol's ordinary JSON error; cancellation releases what the request held.

The output ceiling — max_output_tokens — is optional, and a request stating none is answered under this surface's published default of 32768 tokens; this platform requires a FINITE bound before the upstream call, and a published default is one the caller can read in advance. An explicit zero is refused: it is a request for no output at all.

instructions is implemented and becomes the conversation's leading system turn; a developer turn is carried as a system turn, the two being one role under two names. store is accepted only as false, because this platform retains no response and accepting true would promise a retrieval that cannot happen.

Four members are ACCEPTED AND HAVE NO EFFECT, each saying so in its own description rather than being refused or silently honoured — parallel_tool_calls, prompt_cache_key, client_metadata and text.verbosity.

reasoning is conditional: it is carried to the model ONLY on a route that has proven it forwards a reasoning parameter and is dropped otherwise; it never changes which channels the request is offered, and an answer whose request stated it says which happened in the X-Kumo-Reasoning response header (forwarded or dropped).

include is half of the first group: a value this surface publishes an answer for is forwarded to the supplier — today reasoning.encrypted_content, which is what lets a client replay a reasoning item the supplier itself signed — and any other value has no effect, because asking a supplier for an item this surface does not publish would turn a served answer into a refused one.

A previous_response_id is validated for OWNERSHIP and is not honoured as server-side context: this platform persists no prompt, response or chunk, so there is nothing to continue from and the caller sends its own context.

{
  "input": "<input>",
  "model": "<model>"
}

The request carries:

memberwhat it is
client_metadataobject, optional — Metadata the client keeps about its own session.
includearray of string, optional — Extra members the caller asks the answer to carry.
inputstring or array of ResponsesInputItem, required — The conversation, in either spelling this protocol defines: a bare string, or a list of typed items in order.
instructionsstring, optional — The system prompt, as this protocol carries it: a member of the request rather than a turn of the conversation.
max_output_tokensinteger, optional — The output ceiling.
modelstring, required — The model to answer with: a canonical name or an alias the published catalog carries.
parallel_tool_callsboolean, optional — Whether the model may make several tool calls in one turn.
previous_response_idstring, optional — A response of this organization that this request follows.
prompt_cache_keystring, optional — An opaque key the caller uses to group requests for prompt caching.
reasoningobject, optional — Carried to the model ONLY on a route that has proven it forwards a reasoning parameter, and dropped otherwise, with the X-Kumo-Reasoning response header saying which (forwarded or dropped).
storeboolean, optional — Whether the supplier should retain this response for later retrieval.
streamboolean, optional — Whether to stream the answer.
textResponsesTextConfig, optional — How the answer's text is shaped.
tool_choice"auto" or "none" or "required" or object, optional — What this request requires of its tool list, as a bare mode word or as an object naming one declared tool.
toolsarray of ResponsesTool, optional — The tools this turn may call.

ResponsesInputItem

memberwhat it is
actionobject, optional — What a supplier-side search DID, as the supplier described it and as this surface published it.
argumentsstring, optional — The arguments the call was made with, as the JSON text the model produced.
call_idstring, optional — The call this item is or answers.
contentstring or array of ResponsesInputContentPart, optional — The text of a message item, and the reasoning prose of a reasoning item, in either spelling this protocol defines: a bare string, or a list of typed parts.
encrypted_contentstring, optional — The supplier's own encrypted record of a reasoning item, as it was given to the client.
executionstring, optional — Which side runs a tool_search_call.
idstring, optional — The identity this item carried when the caller last saw it.
inputstring, optional — The model's FREEFORM answer to a custom tool, as the text it produced: a patch, a query, whatever the tool's own grammar admits.
namestring, optional — The tool that was called.
namespacestring, optional — The group the called tool was declared in, on a function_call or a custom_tool_call, when the request that produced the call declared its tools in namespaces.
outputstring or array of ResponsesInputContentPart, optional — The result of running the tool, in either spelling this protocol defines: a bare string, or a list of parts.
role"system" or "user" or "developer" or "assistant", optional — Who is speaking.
statusstring, optional — How far the item got, in this protocol's own vocabulary and carried as the caller stated it.
summaryarray of ResponsesInputContentPart, optional — A reasoning item's summary, in parts of kind summary_text.
toolsarray of object, optional — The namespaces of an additional_tools item, or the ordered declarations of a tool_search_output.
type"message" or "function_call" or "function_call_output" or "additional_tools" or "custom_tool_call" or "custom_tool_call_output" or "tool_search_call" or "tool_search_output" or "reasoning" or "web_search_call", optional — Which kind of item this is.

ResponsesTextConfig

memberwhat it is
formatResponsesTextFormat, optional — The named schema an answer must satisfy.
verbosity"low" or "medium" or "high", optional — How much the answer should say.

ResponsesTool

memberwhat it is
descriptionstring, optional — What the tool or namespace does.
executionstring, optional — Which side runs a TOOL_SEARCH — the reference spells "client" and "server".
external_web_accessboolean, optional — Whether a WEB_SEARCH may reach the open web.
filtersResponsesWebSearchFilters, optional — What a WEB_SEARCH is limited to.
formatResponsesToolFormat, optional — How a CUSTOM tool's freeform answer is shaped.
namestring, optional — The tool's name, as it will come back on the call, or a namespace's client-chosen group name.
parametersobject, optional — The tool's parameters, as the JSON Schema the caller wrote for its own tool.
search_content_typesarray of string, optional — Which kinds of content a WEB_SEARCH may return.
search_context_sizestring, optional — How much search context a WEB_SEARCH should gather.
strictboolean, optional — Whether the supplier must enforce the parameter schema rather than be encouraged toward it.
toolsarray of ResponsesNamespacedTool, optional — The declarations inside a namespace, in client order.
type"function" or "custom" or "tool_search" or "web_search" or "namespace", required — The kind of tool.
user_locationResponsesWebSearchLocation, optional — Where a WEB_SEARCH should answer as though it were.

The answer:

application/jsonResponsesReply
text/event-streamResponsesStreamEvent
on failureResponsesError

ResponsesReply

memberwhat it is
created_atinteger, required — The instant this response was answered, as whole seconds since the Unix epoch.
idstring, required — This request's Kumo identity.
modelstring, required — The model this request named, echoed back exactly as sent.
object"response", required — The kind of object this is.
outputarray of ResponsesOutputItem, required — What the model produced, in order, as typed items.
status"completed" or "incomplete", required — How the answer ended.
usageResponsesUsage, optional — What the supplier reported this request consumed.

ResponsesOutputItem

memberwhat it is
actionobject, optional — What a supplier-side search DID, as the supplier described it.
argumentsstring, optional — The arguments, as the JSON text the supplier produced.
call_idstring, optional — The call's identity, to quote when answering it on the next turn.
contentarray of ResponsesOutputContentPart, optional — The message's content, in parts, and a reasoning item's own reasoning text, in parts of kind reasoning_text.
encrypted_contentstring, optional — The supplier's own encrypted record of a reasoning item.
executionstring, optional — Which side runs a tool_search_call, exactly as the supplier stated it.
idstring, optional — The item's own identity.
inputstring, optional — The model's freeform answer to a CUSTOM tool, as the text it produced.
namestring, optional — The tool that was called.
namespacestring, optional — The group the called tool was declared in, on a function_call or a custom_tool_call, when this request declared its tools in namespaces.
role"assistant", optional — Who is speaking.
statusstring, optional — How far the item got.
summaryarray of ResponsesOutputContentPart, optional — A reasoning item's summary, in parts of kind summary_text.
toolsarray of ResponsesTool, optional — The declarations a tool_search_output returned, in their original order.
type"message" or "function_call" or "custom_tool_call" or "tool_search_call" or "tool_search_output" or "web_search_call" or "reasoning", required — Which kind of item this is.

ResponsesUsage

memberwhat it is
input_tokensinteger, optional — Input tokens the supplier counted, including any it served from its own cache.
input_tokens_detailsResponsesInputTokensDetails, optional — How the input divides, when the supplier said.
output_tokensinteger, optional — Output tokens the supplier counted.
total_tokensinteger, optional — Input and output together.

ResponsesStreamEvent

memberwhat it is
content_indexinteger, optional — The index of the content part this event is about, within its own output item.
deltastring, optional — The fragment a delta event carries: text on response.output_text.delta, the model's own refusal on response.refusal.delta, argument text on response.function_call_arguments.delta and response.tool_search_call_arguments.delta, and a custom tool's freeform input on response.custom_tool_call_input.delta.
itemResponsesOutputItem, optional — The item, on response.output_item.added — opened, so it carries its id and status in_progress, a message an empty content list and a call its identity and an empty argument string — on response.output_item.done, finished, under the same id, and on the three web_search_call stage events, carrying the status the search has reached.
item_idstring, optional — The id of the output item this event is about — the same id the item carries on its response.output_item.added, its response.output_item.done and in the finished output.
logprobsarray of object, optional — The token log probabilities of a text fragment, on response.output_text.delta and response.output_text.done — present on both, and always empty: this platform asks no supplier for them and publishes none.
output_indexinteger, optional — The index of the output item this event is about.
partResponsesStreamContentPart, optional — The content part, on response.content_part.added — opened, so its text is still the empty string — and on response.content_part.done, assembled, carrying exactly the text the fragments between the two events delivered.
refusalstring, optional — The part's assembled refusal, on response.refusal.done: exactly what the part's refusal deltas delivered.
responseResponsesStreamSnapshot, optional — The response, on the response-scoped events: opening on response.created, complete with output and usage on response.completed or response.incomplete, and carrying this protocol's error envelope on response.failed.
sequence_numberinteger, required — This event's position in the stream that carried it, counting from zero and rising by one on every event the customer is sent.
textstring, optional — The part's assembled text, on response.output_text.done: exactly what the part's output_text deltas delivered.
type"response.created" or "response.output_item.added" or "response.content_part.added" or "response.output_text.delta" or "response.refusal.delta" or "response.function_call_arguments.delta" or "response.tool_search_call_arguments.delta" or "response.custom_tool_call_input.delta" or "response.output_text.done" or "response.refusal.done" or "response.web_search_call.in_progress" or "response.web_search_call.searching" or "response.web_search_call.completed" or "response.content_part.done" or "response.output_item.done" or "response.completed" or "response.incomplete" or "response.failed", required — Which event this is.

ResponsesOutputItem

ResponsesOutputItem — see above.

ResponsesStreamContentPart

memberwhat it is
annotationsarray of object, optional — The annotations of an output_text part — present on one, and always empty, as on the finished item's own parts.
refusalstring, optional — The model's own refusal, on a refusal part: the empty string on response.content_part.added, and the assembled refusal on response.content_part.done.
textstring, optional — The part's text, on an output_text part: the empty string on response.content_part.added, and the assembled text on response.content_part.done.
type"output_text" or "refusal", required — The kind of part: the text the model spoke, or its own refusal.

ResponsesStreamSnapshot

memberwhat it is
created_atinteger, required — The instant this response was answered, as whole seconds since the Unix epoch.
errorResponsesErrorBody, optional — This protocol's own error envelope, on response.failed.
idstring, required — This request's Kumo identity, identical on every event of one stream.
modelstring, required — The model this request named, echoed back exactly as sent, on every snapshot.
object"response", required — The kind of object this is.
outputarray of ResponsesOutputItem, optional — What the model produced, in order, on response.completed or response.incomplete.
status"in_progress" or "completed" or "incomplete" or "failed", required — Where the answer stands.
usageResponsesUsage, optional — What the supplier reported this request consumed, on response.completed or response.incomplete.

ResponsesError

memberwhat it is
errorResponsesErrorBody, required

ResponsesErrorBody

memberwhat it is
codestring, optional — The machine-readable reason.
limitRequestLimit, optional — On a request_limit_exceeded refusal, which limit the request exceeded, the limit and the value the request reached; param names the member.
messagestring, required — What went wrong, in a fixed safe sentence.
paramstring, optional — The request member at fault, when one member is at fault.
probestring, optional — On a connect-check refusal only (a model named kumo-connect-check-<32 hex> that no live model answers to, asked with a valid key): kumo-connect-check-<nonce>:<proof>, where proof is the first 16 hex characters of HMAC-SHA256 over the nonce and the key id under a gateway-held key.
reason"welcome_model_cap" or "welcome_spent" or "welcome_photos_spent" or "daily_model_limit" or "daily_common_limit" or "daily_usage_limit" or "native_search" or "no_free_allowance" or "input_too_large" or "request_unbounded" or "not_eligible" or "free_variant_unavailable" or "limits_changed" or "free_limits_exhausted" or "requests_per_minute" or "concurrency", optional — On a free_limit_exhausted or free_rate_limited refusal only — a request that named a free variant (<model>:free) or the alias kumo/free, which is never paid: why it was refused, in a closed vocabulary.
reset_atstring, optional — On a free_limit_exhausted or free_rate_limited refusal, the instant the limit resets, when one exists: the next 00:00 Europe/Moscow for a daily free limit (and for an account whose daily free limits open then), the end of the counted minute for the per-minute limit.
type"invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "rate_limit_error" or "api_error", required — The class of failure, in this protocol's own closed vocabulary.

POST /v1/systemone

Method
POST
Path
/v1/systemone
Auth
Authorization: Bearer <key>
Operation
public.systemone.create

Ask a decision model typed questions about a state and get probabilistic answers.

Ask a decision model typed questions about a state.

OpenRouter's System One protocol for decision models: send a state — free text, a JSON object such as a conversation, or a JSON array such as a list of messages or content parts — and a non-empty questions object keyed by names you choose; the answer carries one entry per question under the same names, in the model's own answers shape, unchanged.

Billing counts input tokens only, as the supplier counts them: this surface produces no output tokens and no image units, and usage.output_tokens is always zero. state and questions together may be at most 25165824 bytes (enough for a photograph sent as base64 inside the state). Streaming is not part of this surface.

{
  "model": "<model>",
  "questions": {},
  "state": "<state>"
}

The request carries:

memberwhat it is
modelstring, required — The catalog model to ask, as the customer names it.
questionsobject, required — The questions, keyed by names the caller chooses; each is the model's own question object (for example {"type":"noul","instructions":"…"}).
statestring or object or array, required — What the questions are about: free text, a JSON object (for example a conversation), or a JSON array (for example a list of messages or of content parts).

The answer:

application/jsonDecisionsResponseBody
on failureDecisionsError

DecisionsResponseBody

memberwhat it is
answersobject, required — One answer per question, keyed by the question's name.
idstring, required — This request's Kumo identity, to quote in a support question.
modelstring, required — The model this request named, echoed back exactly as it was sent.
usageDecisionsUsage, required — What the request cost.

DecisionsUsage

memberwhat it is
input_tokensinteger, required — The input tokens charged for this request.
output_tokensinteger, required — Always zero: this surface bills input tokens only.

DecisionsError

memberwhat it is
errorDecisionsErrorBody, required — The failure.

DecisionsErrorBody

memberwhat it is
codestring, required — The machine-readable reason, shared with every Kumo surface.
messagestring, required — A safe description of the failure.
request_idstring, optional — The Kumo request identifier, for support.
typestring, required — The class of failure.

Every operation above is emitted from the API description this build was compiled against. The whole of this documentation as one Markdown document is described on the machine-readable page.