API reference/Endpoints & examples/Messages

Messages

An Anthropic Messages compatible endpoint, used by Claude Code and the Anthropic SDKs. Requests must include max_tokens, system is a top-level field, and thinking and cache_control prompt caching are supported.

POSThttps://api.wokey.ai/v1/messages· Anthropic Messages compatible

On this pageexpand_more

Example
Headers
Request parameters
How Wokey handles it
Response
Streaming
Error format

Examplelink

For the Anthropic SDKs and Claude Code, set the base URL to https://api.wokey.ai without /v1, because the client appends /v1/messages itself.

curl https://api.wokey.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

Headerslink

Header	Value	Description
`x-api-key`Required	YOUR_API_KEY	Your Wokey API key. Authorization: Bearer YOUR_API_KEY works as well and is what current Anthropic SDKs send by default.
`anthropic-version`	2023-06-01	Optional. The gateway always calls the upstream with 2023-06-01.
`anthropic-beta`	string	Optional. Merged and forwarded to Claude. Models with a 1M context window don't need the context-1m beta.
`Content-Type`Required	application/json	The request body is JSON.
`X-End-User-Id`	string	Optional. Your end user's ID, 1–128 visible ASCII characters. With it, restrictions triggered by repeated violations apply only to that end user.

Request parameterslink

The parameters below are read by the gateway or change its behavior. Other Anthropic parameters are forwarded to Claude as-is.

Parameter	Type	Description
`model`Required	string	A model ID that exactly matches one in the model list.
`max_tokens`Required	integer	Output token limit, a positive integer. Without it the gateway returns 400 and nothing is sent upstream.
`messages`Required	array	The conversation. Every tool_use needs a matching tool_result in the next message, or the gateway returns 400.
`system`	string \| array	The system prompt, at the top level rather than inside messages.
`thinking`	object	Extended thinking. Some newer models accept only adaptive mode, and the gateway adjusts incompatible values by model. Set the thinking effort with output_config.effort.
`cache_control`	object	Prompt cache breakpoints on content blocks, forwarded to Claude as-is. Put one at the end of system and one on the last message.
`stream`	boolean	When true, the response streams as SSE events.
`tools`	array	Tool definitions; tool_choice is supported too.
`temperature`	number	Accepted only by Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, and Haiku 4.5, clamped to 0–1; newer models do not receive it. top_p and top_k are not forwarded to Claude.
`metadata`	object	Not forwarded upstream.
`provider`	object	A Wokey extension that picks or excludes vendors. It is used for routing only and is not forwarded upstream.

How Wokey handles itlink

What the gateway does before and after forwarding, and where it differs from calling the official API directly.

Claude models are forwarded in Messages format without conversion. The gateway adjusts a few parameters by model (see the table) and adds prompt cache breakpoints where needed.
Models with a native Messages API, such as DeepSeek, Kimi, and Grok, are forwarded as-is too. GPT and other models need conversion; then thinking and output_config have no effect and thinking blocks in the history are skipped.
document (PDF) blocks only work on Claude models.
Request bodies sent to Claude are limited to 32 MiB; larger ones return 413 request_body_too_large.
POST /v1/messages/count_tokens counts input tokens.

When a model has several vendors, add a provider object to the request body to pick or exclude vendors. Choosing vendors and their order →

Responselink

JSON

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{ "type": "text", "text": "Hello! How can I help you today?" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 21,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 10
  }
}

The x-wokey-request-id response header is the request's ID at Wokey, and request-id is the ID from Anthropic. Include x-wokey-request-id when you report a problem.
Claude models: input_tokens excludes cache; cache writes and reads are in cache_creation_input_tokens and cache_read_input_tokens.
GPT and other converted models: input_tokens includes cached tokens and cache_read_input_tokens repeats the cached count, unlike Anthropic's convention.

Streaminglink

Events follow Anthropic's order: message_start, content_block_*, message_delta, message_stop.

SSE

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"usage":{"input_tokens":21,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello!"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":10}}

event: message_stop
data: {"type":"message_stop"}

Claude models pass the upstream event stream through unchanged.
For other models the gateway generates events in the same order: usage in message_start is 0, the output_tokens in message_delta is the figure to use, and tool use blocks come last.
An error during the stream is sent as an event: error event.
While waiting for the first upstream byte, the gateway sends periodic SSE comment lines to keep the connection open, which clients ignore.

Error formatlink

JSON

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required for Anthropic Messages requests. Add max_tokens or use /chat/completions for OpenAI-compatible requests."
  }
}

Errors use the Anthropic shape, with error.type set by status, for example 400 invalid_request_error, 401 authentication_error, 402 billing_error, 429 rate_limit_error, and 529 overloaded_error. For what each status means and what to do, see Error codes & troubleshooting →