Endpoints

Messages

POST /v1/messages: the Anthropic Messages API, currently serving Claude Code.

This is the endpoint Claude Code talks to: point Claude Code at Roteo and it calls /v1/messages for you. Requests from other clients currently get 403; for direct Claude requests from your own code, use Chat Completions.

POSThttps://api.roteo.ai/v1/messages

Request parameters

modelstringrequired

The model ID to call: a Claude model, for example claude-sonnet-4-6, or deepseek-v4.1-flash-1017. Any other model ID returns 400, naming the endpoint that serves it. See Models.

max_tokensintegerrequired

The maximum number of tokens to generate before stopping. Large values are capped by a server ceiling; when that happens the response carries an x-roteo-clamped-max-tokens header with your original value.

messagesarrayrequired

The conversation so far, as an array of { role, content } objects. role is user or assistant; content is a string or an array of content blocks (text, images, tool results).

systemstring | array

A system prompt: instructions and context applied to the whole conversation.

temperaturenumberdefault: 1.0

Amount of randomness, between 0.0 and 1.0. Lower is more deterministic. Stripped where a model no longer accepts it; see Parameter repair below.

top_pnumber

Nucleus sampling. Use either temperature or top_p, not both.

top_kinteger

Only sample from the top K options for each token.

stop_sequencesarray

Custom text sequences that will stop generation.

streambooleandefault: false

When true, tokens are streamed back as server-sent events. See Streaming.

toolsarray

Tool definitions the model may call. See Tool use.

tool_choiceobject

Controls whether and which tool the model must use (auto, any, or a specific tool).

thinkingobject

Enable extended thinking with a token budget. On newer models this is adapted automatically to effort. See Reasoning.

metadataobject

An object with a user_id and other opaque metadata about the request.

Any other field from the Anthropic Messages API is accepted and passed through.

Parameter repair

Newer models reject some legacy sampling controls. Roteo adjusts the request instead of failing it: temperature, top_p and top_k are stripped where a model no longer accepts them, and a legacy fixed-budget thinking is rewritten to the model's effort control. Anything adjusted is listed in the x-roteo-repaired-params response header.

Response

A successful call returns a message object:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [{ "type": "text", "text": "Hello! How can I help you today?" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 11,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
json · 15 lines

The usage block is what you are billed on.

Prompt caching

A stable prefix of the request can be cached, so repeat calls that share it are billed at a fraction of the input price. The last block to cache is marked with cache_control: a system prompt, the tools array or a message block. Claude Code does this for you.

A cache write is billed at 2x the input rate and a cache read at roughly a tenth of it, over a 1-hour cache window. Both appear in the response usage as cache_creation_input_tokens and cache_read_input_tokens.

Context editing

For long agent runs, context_management has the model trim older tool results and turns automatically as the context window fills, instead of resending a hand-pruned history each turn. Roteo forwards it unchanged and adds the beta header it requires, so it behaves the same as calling Anthropic directly.

DeepSeek V4.1 Flash

deepseek-v4.1-flash-1017 takes the same request as a Claude model: tools, images (inside tool results too), streaming and thinking. It is paid from your wallet at its own price; promotional credit covers Claude and GPT only. Prompt caching is automatic: a repeated prefix is billed at its cached-input rate, with no cache_control needed and no cache-write surcharge. PDF documents and web search are not supported.

A conversation can move between DeepSeek and Claude. Before a Claude model sees the history, Roteo removes the thinking blocks DeepSeek wrote (Claude cannot read them) and lists thinking in x-roteo-repaired-params. Setup for Claude Code is in Use DeepSeek V4.1 Flash.

Response headers

HeaderMeaning
x-request-idTrace ID for the request. Include it in any support question.
x-roteo-billing-chainThe chain this call settled on.
x-roteo-discount-bpsYour ROTEO lock discount on this call, in basis points (800 is 8%). 0 when your account has no tier.
x-roteo-repaired-paramsAny stale parameters that were adjusted for the target model.
x-roteo-clamped-max-tokensPresent when max_tokens was reduced to the server ceiling.

Errors

See Errors for status codes. Common cases: 400 (a model this endpoint does not serve), 401 (bad key), 402 (wallet underfunded for this call), 403 (a client other than Claude Code), 429 (rate limited).

Messages | Roteo