Messages API

Use POST /v1/messages when your application already uses the Messages request and content-block format. Keiro accepts that wire shape, serves it with the same public eb1 models as the other completion endpoints, and returns a Messages-style response.

On this page 1 of 9

Send a message#

Run a curl request Shell
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eb1-preview",
    "max_tokens": 256,
    "system": "Answer in one concise sentence.",
    "messages": [
      {
        "role": "user",
        "content": "Why are idempotency keys useful?"
      }
    ]
  }' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER"

Read generated text from the text blocks in content. A buffered response has this customer-visible shape:

JSON payload JSON
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Idempotency keys let a safe retry reuse the original result instead of running twice."
    }
  ],
  "model": "eb1-preview",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 19
  }
}

IDs, text, and token counts vary by request. Depend on the field layout, not the sample values.

The three input-side fields are disjoint, matching Anthropic's native Messages usage semantics: input_tokens counts the portion of the prompt served from neither cache, cache_read_input_tokens counts prompt tokens served from a prompt cache, and cache_creation_input_tokens counts prompt tokens written to one. input_tokens + cache_read_input_tokens + cache_creation_input_tokens equals the full prompt, so a client that sums the three fields — Claude Code's context gauge does — reads the real context size. All three fields are always present. On a stream, the message_start usage carries zero for both cache fields — cache counts, like output_tokens, are only known at the terminal message_delta.

Deprecated (2026-08-08): additive-subset usage shape. Messages usage previously rendered input_tokens as the full inclusive prompt count with the two cache fields as subsets of it. That shape is retired for all Messages consumers; the disjoint semantics above are the contract and are what Keiro returns now. If your integration read input_tokens as the inclusive prompt total, sum input_tokens + cache_read_input_tokens + cache_creation_input_tokens to recover the old value. Responses with zero cache activity are byte-identical under both shapes.

Supported request fields#

The public Messages surface supports these top-level fields:

  • model, messages, and optional top-level system
  • max_tokens, temperature, top_p, and stop_sequences
  • stream
  • tools, tool_choice, and parallel_tool_calls. The boolean tool_choice.disable_parallel_tool_use on an auto, any or tool choice is honored. Sending it as true together with parallel_tool_calls: true is refused with a 400.
  • thinking with type enabled, adaptive or disabled, and an optional display string; enabled thinking requires a positive budget_tokens. Enabled thinking asks for thinking summary blocks unless display is omitted. Adaptive thinking asks for them only when display is summarized. A response can still carry none.
  • output_config with effort, format, or task_budget
  • metadata. Keiro reads a session ID from metadata.user_id and doesn't send your user_id value to model providers. The other keys hold at most 16 pairs, with keys up to 64 characters and values up to 512 characters; a request over any of these bounds is refused with a 400.
  • idempotency_key, with the request-header form preferred for HTTP clients
  • context_management and safeguards, which Claude Code sends, are accepted and ignored. Keiro manages provider context itself, and replies carry no safeguard_results, so Claude Code's auto mode reviews each tool call with its own local classifier.

On eb1 models, temperature and top_p apply only when the model serving the request takes them. When it does not, Keiro leaves them out of the call and does not refuse the request.

On eb1 models, unknown fields fail closed with a 400 invalid_request_error whose message and error.param name the field (see Errors). Fields Keiro holds back on purpose, such as service_tier, container and betas, are refused with a 409 capability_conflict instead. Do not assume that a field from another Messages implementation is available on an eb1 model until it is listed here.

On every model, Keiro does not read the anthropic-version or anthropic-beta request headers, and sending a beta header does not switch that beta on. Replies carry the same x-ratelimit-* rate-limit headers as the other API formats (see Rate and spend limits) and no other rate-limit header family.

On models outside the eb1 family, Keiro forwards any other top-level field unchanged, and that model's API accepts or rejects it. Because your beta header is not passed on, a field that needs a beta may be rejected; the rejection is a 400 whose message names the forwarded fields. Only keys with access to models outside the eb1 family can make those requests: any other key gets a 403 model_not_available for a model Keiro offers to other accounts, and a 404 model_not_found for any other model ID. Fields that carry provider cost, account state or hosted execution are refused on every model: service_tier, inference_geo, top-level cache_control, fallbacks, container, compaction, diagnostics, fallback_credit_token, workspace_id, user_profile_id, mcp_servers and betas. speed is refused except for "fast" on eb1-frontier-preview, as described below.

Task budget#

On models outside the eb1 family that support task budgets, pass a budget for the whole task using "output_config": {"task_budget": {"type": "tokens", "total": 200000}}. The object must contain exactly type and total: type must be "tokens" and total must be an integer of at least 20000 (booleans are rejected). Keiro forwards the caller's value and enables the required beta, together with any supplied effort or output format, on both buffered and streaming requests. The task budget covers the agentic loop; max_tokens still caps a single reply. Keiro never chooses or inserts a task budget. As with any request to a model outside the eb1 family, this needs a key with access to those models; any other key gets the 403 or 404 described above.

Models that do not support task budgets, including every eb1 model id, return a caller-fixable 400 when a task budget is supplied. Malformed budgets also return 400 before dispatch. This field is supported only on /v1/messages; /v1/responses and Chat Completions gain no new request fields.

Tool types#

Besides function tools declared with name and input_schema, Messages accepts the client-executed tool types bash_20250124, text_editor_20250124, text_editor_20250429, text_editor_20250728 and memory_20250818 on eb1 models. The model plans the call; your client runs it and answers with a tool_result block.

These tool types are refused: code execution (code_execution_*), web fetch (web_fetch_*), mcp_toolset, advisor_20260301, and the tool_search_tool_* types.

Content blocks#

User and assistant messages accept strings or non-empty content-block arrays. Supported customer workflows include text, top-level user image blocks, user document blocks (the same sources as in tool results, below), and the tool_use / tool_result history used for function calling.

tool_result content accepts a string or an array of these blocks, and content may be left out for an empty result:

  • text and image, so a coding harness can return screenshots as tool output. Every image in the request, including those inside tool results, counts toward the request image limits in Images and vision.
  • document with a plain-text source (media_type text/plain) or a content source of text and image blocks. The model reads the title and the text.
  • document with a base64 PDF source. PDF input is not currently enabled, so these return a 400 saying file inputs are not enabled. When it is, the PDF follows the tool results in the same turn and counts toward the request's file limits. URL and file-ID sources return a 400.
  • search_result. The model reads its title, source and text. Citations are not available, so a search_result with citations returns a 400.
  • tool_reference, as a tool search returns it. The model reads that the tool is loaded, or that it is not available when tools no longer declares it.

Any other block type returns a 400 naming the block's path and type. See Tool calling for tool history.

An assistant thinking block replayed with an empty or null signature is treated as unsigned, like one with no signature: it is accepted and never sent on as a signed block. Any other non-string or blank signature returns a 400.

System-role messages inside messages carry text blocks. When an MCP server connects mid-session, Claude Code also sends a tool_addition block there that references a tool declared in tools. Keiro accepts it. Keiro does not implement defer_loading; such tools are exposed like any other. Inline tool_definition additions and tool_removal blocks return a 400, and Claude Code then declares the tools in tools instead.

Stream a response#

Set stream to true to receive Messages-style server-sent events. A normal text stream follows this lifecycle:

  1. message_start
  2. content_block_start
  3. one or more content_block_delta events
  4. content_block_stop
  5. message_delta, including the terminal stop reason and final usage
  6. message_stop

When thinking summaries are returned (enabled thinking unless display is omitted, or adaptive thinking with display set to summarized), one or more thinking content blocks arrive before the text block: a content_block_start with block type thinking, thinking_delta deltas carrying the thinking text, then content_block_stop, all closing before the text block opens. These blocks carry summary text constructed by the API and are unsigned: their signature is the empty string, in non-streaming responses and in the stream, which opens the block with "signature": "" and sends no signature_delta for it. Do not round-trip them to a provider as signed thinking blocks.

When the model calls a tool, the tool_use block streams live: a content_block_start with the block's id, name, and empty input arrives as soon as the model commits to the call (closing any open text block first), followed by content_block_delta events of type input_json_delta whose partial_json fragments concatenate to the input, then content_block_stop and a message_delta with stop_reason: "tool_use". If max_tokens ends the response while the input is still streaming, the block closes with the fragments delivered so far and the message_delta carries stop_reason: "max_tokens"; treat that block as incomplete, exactly as with a native Anthropic stream.

Streams, and long non-streaming requests, live as long as the model keeps working; no wall-clock limit ends them, whatever thinking.budget_tokens requests — see Streaming.

A failure after streaming begins arrives as an in-band error event with a sanitized error.type, error.code, and error.message. Retriable failures also include error.retry_after_seconds.

Faster frontier requests#

Set "speed": "fast" with "model": "eb1-frontier-preview" for a faster response. This setting is available on paid self-serve plans and beta and alpha accounts. It is separate from reasoning effort and is unavailable on other models.

When the faster speed is served, it costs $20 per million input tokens, $2 per million cached input tokens, $100 per million output tokens, and $360 per million reasoning tokens. Very long prompts and requests under heavy load can run at standard speed, and those bill at standard rates. The terminal response reports what was served: usage.speed is "fast" or "standard". In-progress streaming events omit this field.

Ultra frontier requests#

Set "output_config": {"effort": "ultra"} with "model": "eb1-frontier-preview" to have eb1 orchestration use more models and deeper reasoning on a request. It is opt-in on each request: max does not turn it on, and the other eb1 models ignore ultra. It is available on paid self-serve plans and on alpha, beta and enterprise accounts; on any other account the request runs as a normal request. Compare it with a normal request on your own prompts before relying on it.

It costs more and turns take longer. A request can take many minutes, and a streamed one may send only ping events before its first text; see Long requests. Billing works as on any eb1 request, and the added models and reasoning appear as reasoning tokens; see Usage and billing. The request also holds more of your spend limit while it runs. A small max_tokens lowers the reasoning depth, so set it as high as you can for the deepest reasoning. Some tool requests, including those that use provider-hosted tools or remote MCP servers, use one model at the deepest reasoning.

The x-keiro-reasoning-mode response header reports the mode the request ran in: ultra, or standard when it ran as a normal request at normal cost.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console