Messages API
The Anthropic Messages shape, translated at the edge onto the same order pipeline as chat. A request here is priced, queued, charged, logged and replayed exactly as a chat request; the body, the events and the error envelope are Anthropic's.
Create a message
POST /v1/messages
curl https://api.openfill.ai/v1/messages \ -H "x-api-key: $OPENFILL_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model": "placeholder-large", "max_tokens": 1024, "messages": [{"role": "user", "content": "hi"}], "max_price": 0.10}'Headers
| Header | Rule |
|---|---|
| x-api-key | Your OpenFill key. Authorization: Bearer is accepted too, and wins when both are sent. |
| anthropic-version, anthropic-beta | Accepted with any value and ignored. |
| X-Max-Price, X-Expires-After, Idempotency-Key | As on chat. This is how a tool with no body field carries the max price. |
Request body
The Anthropic fields first, then the OpenFill extensions, which carry the same names and rules as on chat. A field absent from this table is forwarded to the model untouched.
| Field | Type | Default | Meaning |
|---|---|---|---|
| model | string | the default model | A served model id or alias. |
| max_tokens | integer | required | The output cap, clamped down to the model's max output length. 0 is 400. |
| system | string or array | none | A string, or text blocks joined with a blank line, as the system message. |
| messages | array | required | Roles user, assistant and system. Content is a string or blocks: text, tool_use, tool_result and thinking. A tool_result becomes a tool message placed before the user text. |
| tools | array | none | name, description and input_schema become a function tool. cache_control and the other Anthropic-only keys are dropped. |
| tool_choice | object | auto | auto, any, a named tool, or none. disable_parallel_tool_use turns parallel_tool_calls off. |
| temperature, top_p | number | none | Forwarded. top_k is dropped. |
| stop_sequences | array | none | Up to four strings of up to 256 characters. |
| stream | boolean | false | Server-sent events, in the Anthropic event vocabulary. |
| metadata.user_id | string | none | Forwarded as user. |
| thinking | object | none | Accepted and ignored, as are context_management, cache_control and service_tier, so a client that sends them by default keeps working. Reasoning is the model's own decision. |
| output_config.format | object | none | A json_schema becomes response_format for the model. |
| max_price | number | key or account | The most you will pay, in USD per 1M input tokens at the reference mix. None anywhere is 400 missing_bid. |
| price_lock | boolean | account setting | Bid the lower of the published quote and max_price, and start within the execute window or expire with 429 capacity_unavailable. |
| max_wait | integer | account setting | Seconds an unlocked order may wait. Alias expires_after. |
| store, retention_days | as chat | none | store: false keeps nothing durable; retention_days keeps it for fewer days. |
Refused with 400
| Sent | Why |
|---|---|
| image, document and other non-text blocks | Text only. Nothing is charged. |
| tools with a built-in type | Only function tools run here. |
| mcp_servers | Server-side MCP is not served. |
| detached: true | The stored result is chat-shaped, so the detached path is POST /v1/chat/completions. |
Response
json
{ "id": "msg_<order_id>", "type": "message", "role": "assistant", "model": "placeholder-large", "content": [ {"type": "thinking", "thinking": "...", "signature": ""}, {"type": "text", "text": "..."}, {"type": "tool_use", "id": "...", "name": "get_weather", "input": {"city": "Boston"}} ], "stop_reason": "tool_use", "stop_sequence": null, "usage": {"input_tokens": 234, "output_tokens": 56, "cache_read_input_tokens": 1000, "cache_creation_input_tokens": 0, "x_market": {"level_at_execution": 0.23, "bid": 0.5, "charged_usd": 0.0023}}}| Field | Meaning |
|---|---|
| content | A thinking block when the model sent reasoning, then the text, then one tool_use block per call. A block absent from the answer is absent from the list. |
| stop_reason | end_turn on a normal finish, max_tokens when the cap stopped it, tool_use when the model called a tool, stop_sequence when one matched. |
| usage.input_tokens | The uncached prompt tokens, as Anthropic counts them; cache_read_input_tokens is the cached share. cache_creation_input_tokens is always 0. |
| usage.x_market | The receipt: the price the order was charged at, what it bid, and the debit. |
Streaming
200 and a text/event-stream body in the Anthropic event vocabulary, each frame an event: line and a data: line.
a text answer, in order
event: message_start <- at once, with a placeholder usageevent: ping <- every 10 s while the order waits, and while it generatesevent: content_block_startevent: content_block_delta <- text_delta per fragmentevent: content_block_stopevent: message_delta <- stop_reason and the final usage with x_marketevent: message_stop| Case | Events |
|---|---|
| A tool call | content_block_start with the tool_use id and name, input_json_delta with partial_json per fragment, content_block_stop. |
| Reasoning before the answer | A thinking block with thinking_delta events and one signature_delta, closed before the text opens. |
| An error after the stream opened | One error event carrying the envelope below, then the body ends. The status stays 200 and nothing is charged. |
The ping every ten seconds is a parsed Anthropic event and it carries bytes, so both of Claude Code's watchdogs stay quiet through a queue. Its whole-request timeout, ten minutes by default, is the reader's to raise for a longer wait.
Count tokens
POST /v1/messages/count_tokens
curl https://api.openfill.ai/v1/messages/count_tokens \ -H "x-api-key: $OPENFILL_API_KEY" -H "Content-Type: application/json" \ -d '{"model": "placeholder-large", "messages": [{"role": "user", "content": "hi"}]}'json
{"input_tokens": 12}The same body without max_tokens. The count is the gateway's own prompt estimate, the arithmetic it prices a request with, so it is close rather than exact. It creates no order and is never charged. Claude Code reads it for its context gauge; without it the gauge would be fed through a paid request.
Errors
Every error on these two routes is the Anthropic envelope, with the gateway's message unchanged and its code kept beside the type so missing_bid and capacity_unavailable stay machine-readable.
json
{"type": "error", "error": {"type": "rate_limit_error", "message": "...", "code": "capacity_unavailable"}}| Status | error.type | When |
|---|---|---|
| 400 | invalid_request_error | A bad body, missing_bid, model_deprecated, a bad header. |
| 401 | authentication_error | The key. |
| 402 | billing_error | insufficient_balance at the current level. |
| 403 | permission_error | The account is suspended or being deleted. |
| 404 | not_found_error | model_not_found, or an unknown route. |
| 408 | timeout_error | order_expired: the wait passed max_wait. |
| 409 | conflict_error | order_canceled, or idempotency_error. |
| 410 | not_found_error | result_unavailable on a replay with nothing stored. |
| 413 | request_too_large | The body is over the limit. |
| 429 | rate_limit_error | A ceiling, or capacity_unavailable on a missed lock window. Retry-After where one is sent. |
| 500 | api_error | Our side. |
| 502 | api_error | The backend failed mid-stream. Nothing charged. |
| 503 | overloaded_error | The gateway is restarting or the backend is unavailable. |