API reference

Messages

An Anthropic-compatible, stateless Messages surface. Claude Code envelopes, images, client tools and extended thinking are admitted only when one selected route preserves the complete requested semantics.

POST https://router.omnitools.ai/v1/messages

Authentication and version

Send the Team API key and the supported Anthropic protocol version.

x-api-key: $OTRouter_API_KEY · anthropic-version: 2023-06-01

Authorization: Bearer is also accepted; dual credentials must match. Content-Type is application/json. Claude Code may use ?beta=true. Every comma-separated anthropic-beta identifier must be explicitly allowed by the selected native route. The direct-browser header, when present, must be true. Documented Claude Code attribution headers are validated and forwarded only on that route.

Create a message

max_tokens is required for every Messages request.

curl https://router.omnitools.ai/v1/messages \
  -H "x-api-key: $OTRouter_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-fable-5",
  "max_tokens": 160,
  "messages": [
    {
      "role": "user",
      "content": "Name one property of a clear API contract."
    }
  ]
}'

Request parameters

Documented fields are validated and then matched against an exact route profile. Claude Code beta fields require a valid, route-allowlisted anthropic-beta identifier; unknown beta identifiers and arbitrary future provider extensions are rejected.

Parameter	Requirement	Description
model	Required	Stable OTRouter model ID from the model catalog.
max_tokens	Required	Positive output-token limit below the selected model's maximum.
messages	Required	1–100,000 user, assistant or system messages with supported content blocks. A system role inside messages requires native Messages.
system	Optional	A non-empty string or array of text blocks used as the leading instruction.
stop_sequences	Optional	Up to four non-empty strings. The selected model route must support stop sequences.
temperature	Optional	Number from 0 through 1.
top_p	Optional	Number from 0 through 1.
stream	Optional · default false	Returns named Anthropic server-sent events when true.
tools	Optional	Up to 128 client tools with object input_schema. Route-verified Claude Code client-tool fields may require native Messages; hosted and server tools are rejected.
tool_choice	Optional	Object type auto, any, none or tool. auto, any and tool accept disable_parallel_tool_use.
thinking	Optional	disabled, adaptive, or enabled with budget_tokens of at least 1024 and less than max_tokens. display, when present, is beta-gated and only accepts omitted or summarized.
context_management / metadata / output_config / block cache_control	Optional · native	The verified Claude Code envelope subset is preserved only by its eligible native Messages route.
/v1/messages/count_tokens	Authenticated · native	Returns the upstream tokenizer's input_tokens for a supported native model. It is rate-limited, unbilled and does not create a generation Request, Attempt or Ledger entry.

Content blocks and tool turns

Messages preserves Anthropic native shapes when their semantics require a native route; the common text/tool subset may use a compatible route.

User content

Accepts text, tool_result and image blocks. Images use URL sources or JPEG, PNG, GIF or WebP base64 and require a route with verified image support.

Assistant content

Accepts text, thinking, redacted_thinking and tool_use. The verified native route preserves signed thinking for client replay and rejects unexpected response blocks or fields.

Tool definitions

Client tools require object input_schema. OTRouter neither executes nor passes through hosted or server-tool definitions and output blocks.

Extended thinking

adaptive and enabled thinking allow only auto or none tool choice. adaptive requires native Messages; thinking.display also requires the matching route-allowlisted beta and only accepts omitted or summarized.

Native semantics

Native-only fields, a system role inside messages and image tool results select a native Messages route. Router never performs a lossy Chat Completions downgrade for them.

Automatic routing

Router prefers native Messages. Common semantics may use a compatible route; native-only Claude Code or Anthropic semantics restrict selection to native Messages routes.

Routing is automatic and private. Router filters by the requested protocol and capabilities, then applies configured priority and internal cost. Fallback keeps the public model ID. Fixed-price models use their published model rates; supply-priced models use the applicable quote for the route actually used, so fallback may change the rate charged.

Streaming events

With stream: true, every SSE event name matches the type in its JSON payload.

message_start opens the message; ping may appear while it is active.
content_block_start opens verified text, thinking, redacted_thinking or client-tool output.
content_block_delta carries the corresponding validated text, thinking, signature or tool-input delta.
content_block_stop closes the current block.
message_delta reports stop_reason and terminal usage; message_stop ends the stream.
error is the terminal stream failure event; upstream identity and raw provider errors are replaced with a stable public error.

Message object

The verified native route preserves text, signed thinking, redacted_thinking, client tool calls, normalized usage and supported stop details. Unknown provider fields and events fail closed instead of entering the public response.

Minimal response

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [
    {
      "type": "text",
      "text": "…"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 24,
    "output_tokens_details": {
      "thinking_tokens": 0
    }
  }
}

Unsupported parameters

Accepted fields are not silently dropped. Features outside an exact route profile are rejected before generation rather than forwarded speculatively.

document input blockshosted or server toolsmcp_servers and container executionnon-empty citationsunknown response blocks or stream events

Unlisted or unverified fields are rejected. Native-only fields require an eligible Messages route, images require verified route capability, and beta-gated fields require anthropic-beta.

Errors

Responses and Chat Completions return message, type, param and code with x-request-id. Messages maps the HTTP status to the Anthropic error shape, omits code and also includes request-id.

HTTP	Router code	Description
400	invalid_parameter	The JSON shape, parameter value, protocol header or requested feature is invalid.
401	invalid_api_key	The API key is missing, malformed, expired, deleted or unknown.
402	insufficient_credits	The Team has no available Credits for a new request.
404	model_not_found	The requested model is unavailable.
413	payload_too_large	The JSON request body exceeds 8 MiB.
429	api_key_spend_limit_exceeded	The API key reached one of its rolling spend limits.
502	upstream_error / invalid_upstream_response	Model execution was rejected or returned an invalid response.
503	upstream_unavailable / route_unavailable	No eligible route completed the request before the routing deadline.

Keep x-request-id (or request-id for Messages) when contacting support or inspecting the request in Console.