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, for example claude-sonnet-4-6. 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.

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-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: 401 (bad key), 402 (wallet underfunded for this call), 403 (a client other than Claude Code), 429 (rate limited).

Messages | Roteo