> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/messages.md).

# Messages

Anthropic-native Messages API for prompt-cache-preserving passthrough.

## Create a message (Anthropic-native)

> Anthropic-native Messages API. Accepts requests in Anthropic's wire format and forwards\
> them to the upstream Anthropic provider byte-for-byte, preserving native features such as\
> \`cache\_control\` for prompt caching. Use this endpoint when the client already speaks\
> Anthropic — it avoids the OpenAI translation layer that silently strips \`cache\_control\`.<br>

```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Messages","description":"Anthropic-native Messages API for prompt-cache-preserving passthrough."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"CreateMessageRequest":{"type":"object","description":"Anthropic-native Messages API request body. Forwarded byte-for-byte to the upstream\nprovider — `cache_control` markers are preserved exactly where the client placed them\n(system blocks, message content blocks, tool definitions, top-level).\n","properties":{"model":{"type":"string","description":"Model identifier or alias resolved against the company's configured models. Must resolve to an Anthropic-provider model."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InputMessage"}},"system":{"description":"System prompt as a single string or as an array of text blocks (each may carry `cache_control`).","oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/SystemBlock"}}]},"max_tokens":{"type":"integer","minimum":0,"description":"Maximum output tokens. Set to `0` to warm the prompt cache without generating output."},"temperature":{"type":"number","minimum":0,"maximum":1,"nullable":true,"description":"Sampling temperature. Note: the newest Claude models (Sonnet 4.6+/5) reject `temperature`, `top_p`, and `top_k` as deprecated.\n"},"top_p":{"type":"number","nullable":true,"description":"Nucleus sampling. Rejected as deprecated by the newest Claude models."},"top_k":{"type":"integer","nullable":true,"description":"Top-k sampling. Rejected as deprecated by the newest Claude models."},"stop_sequences":{"type":"array","nullable":true,"items":{"type":"string"}},"stream":{"type":"boolean","default":false,"nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata","nullable":true},"tools":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"$ref":"#/components/schemas/ToolChoice","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true},"thinking":{"$ref":"#/components/schemas/ThinkingConfig","nullable":true},"output_config":{"$ref":"#/components/schemas/OutputConfig","nullable":true},"service_tier":{"type":"string","enum":["auto","standard_only"],"nullable":true,"description":"Anthropic API service tier. Note: models hosted on Vertex AI (currently all Claude models on the platform) reject this parameter.\n"},"container":{"type":"string","nullable":true,"description":"Container reference for code-execution tools. Note: models hosted on Vertex AI (currently all Claude models on the platform) reject this parameter.\n"}},"required":["model","messages","max_tokens"]},"InputMessage":{"type":"object","description":"A single input message in the `messages` array.","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"Either a plain string or an array of content blocks.","oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ContentBlock"}}]}},"required":["role","content"]},"ContentBlock":{"description":"A content block within a message's `content` array. Discriminator is `type`.\nStrict-typed concrete subtypes cover the full Anthropic Messages API surface;\n`cache_control` is forwarded byte-for-byte where present.\n","oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"},{"$ref":"#/components/schemas/DocumentBlock"},{"$ref":"#/components/schemas/ToolUseBlock"},{"$ref":"#/components/schemas/ToolResultBlock"},{"$ref":"#/components/schemas/ThinkingBlock"},{"$ref":"#/components/schemas/RedactedThinkingBlock"},{"$ref":"#/components/schemas/ServerToolUseBlock"},{"$ref":"#/components/schemas/WebSearchToolResultBlock"},{"$ref":"#/components/schemas/SearchResultBlock"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TextBlock","image":"#/components/schemas/ImageBlock","document":"#/components/schemas/DocumentBlock","tool_use":"#/components/schemas/ToolUseBlock","tool_result":"#/components/schemas/ToolResultBlock","thinking":"#/components/schemas/ThinkingBlock","redacted_thinking":"#/components/schemas/RedactedThinkingBlock","server_tool_use":"#/components/schemas/ServerToolUseBlock","web_search_tool_result":"#/components/schemas/WebSearchToolResultBlock","search_result":"#/components/schemas/SearchResultBlock"}}},"TextBlock":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true},"citations":{"type":"array","nullable":true,"items":{"type":"object","properties":{"type":{"type":"string"},"cited_text":{"type":"string"},"document_index":{"type":"integer"},"document_title":{"type":"string","nullable":true},"start_char_index":{"type":"integer"},"end_char_index":{"type":"integer"},"start_page_number":{"type":"integer"},"end_page_number":{"type":"integer"},"start_block_index":{"type":"integer"},"end_block_index":{"type":"integer"}},"required":["type"]}}},"required":["type","text"]},"CacheControlEphemeral":{"type":"object","description":"Marks a caching breakpoint for prompt caching. Attach it to any cacheable element —\nsystem text blocks, message content blocks, tool definitions, `tool_use`, `tool_result`,\n`search_result`, or `document` blocks. A request may carry up to four such breakpoints.\nWhen supplied at the top level, it is automatically applied to the last cacheable block.\n","properties":{"type":{"type":"string","enum":["ephemeral"]},"ttl":{"type":"string","description":"How long the cached prefix stays valid. Omitting it falls back to `5m`; `1h` works without any beta header.","enum":["5m","1h"]}},"required":["type"]},"ImageBlock":{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"source":{"$ref":"#/components/schemas/ImageSource"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","source"]},"ImageSource":{"oneOf":[{"$ref":"#/components/schemas/ImageSourceBase64"},{"$ref":"#/components/schemas/ImageSourceURL"}]},"ImageSourceBase64":{"type":"object","properties":{"type":{"type":"string","enum":["base64"]},"media_type":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp"]},"data":{"type":"string","description":"Base64-encoded image bytes."}},"required":["type","media_type","data"]},"ImageSourceURL":{"type":"object","properties":{"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"DocumentBlock":{"type":"object","properties":{"type":{"type":"string","enum":["document"]},"source":{"$ref":"#/components/schemas/DocumentSource"},"title":{"type":"string","nullable":true},"context":{"type":"string","nullable":true},"citations":{"$ref":"#/components/schemas/CitationsConfig","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","source"]},"DocumentSource":{"oneOf":[{"$ref":"#/components/schemas/DocumentSourceBase64"},{"$ref":"#/components/schemas/DocumentSourceURL"},{"$ref":"#/components/schemas/DocumentSourceText"},{"$ref":"#/components/schemas/DocumentSourceContent"}]},"DocumentSourceBase64":{"type":"object","properties":{"type":{"type":"string","enum":["base64"]},"media_type":{"type":"string","enum":["application/pdf"]},"data":{"type":"string"}},"required":["type","media_type","data"]},"DocumentSourceURL":{"type":"object","properties":{"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"DocumentSourceText":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"media_type":{"type":"string","enum":["text/plain"]},"data":{"type":"string"}},"required":["type","media_type","data"]},"DocumentSourceContent":{"type":"object","properties":{"type":{"type":"string","enum":["content"]},"content":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"}]}}},"required":["type","content"]},"CitationsConfig":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"ToolUseBlock":{"type":"object","properties":{"type":{"type":"string","enum":["tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object","description":"Arguments passed to the tool, matching the input schema the client declared for it."},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","id","name","input"]},"ToolResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"tool_use_id":{"type":"string"},"content":{"description":"Either a plain string or an array of text/image content blocks.","oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"}]}}]},"is_error":{"type":"boolean","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","tool_use_id"]},"ThinkingBlock":{"type":"object","properties":{"type":{"type":"string","enum":["thinking"]},"thinking":{"type":"string"},"signature":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","thinking","signature"]},"RedactedThinkingBlock":{"type":"object","properties":{"type":{"type":"string","enum":["redacted_thinking"]},"data":{"type":"string"}},"required":["type","data"]},"ServerToolUseBlock":{"type":"object","description":"A built-in tool call (such as `web_search` or `code_execution`) that the provider runs on its own side.","properties":{"type":{"type":"string","enum":["server_tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","id","name","input"]},"WebSearchToolResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["web_search_tool_result"]},"tool_use_id":{"type":"string"},"content":{"description":"Either an array of search results or an error block.","oneOf":[{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["web_search_result"]},"url":{"type":"string"},"title":{"type":"string"},"encrypted_content":{"type":"string"},"page_age":{"type":"string","nullable":true}},"required":["type","url","title","encrypted_content"]}},{"type":"object","properties":{"type":{"type":"string","enum":["web_search_tool_result_error"]},"error_code":{"type":"string"}},"required":["type","error_code"]}]},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","tool_use_id","content"]},"SearchResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["search_result"]},"source":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"content":{"type":"array","items":{"$ref":"#/components/schemas/TextBlock"}},"citations":{"$ref":"#/components/schemas/CitationsConfig","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","content"]},"SystemBlock":{"type":"object","description":"A system prompt content block. Supports `cache_control` for caching the system prefix.","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","text"]},"Metadata":{"type":"object","description":"Optional request metadata passed through to the provider. The `user_id` field helps the provider associate the request with an end user.","properties":{"user_id":{"type":"string","nullable":true}}},"Tool":{"description":"Tool definition. Either a custom tool (function with input_schema) or a built-in server tool (typed by versioned `type`).","oneOf":[{"$ref":"#/components/schemas/CustomTool"},{"$ref":"#/components/schemas/ServerTool"}]},"CustomTool":{"type":"object","description":"A function tool that the client defines and implements.","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","description":"A JSON Schema object that defines the shape of the tool's input arguments."},"type":{"type":"string","enum":["custom"],"description":"Optional type marker. Leave it out for legacy custom tools, or set it to `custom` when you need to be explicit."},"strict":{"type":"boolean","description":"Whether to enforce strict schema adherence for this tool's input. Requires `additionalProperties: false` and every property listed in `required` on `input_schema`. Omitted leaves the provider's own default.\n"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["name","input_schema"]},"ServerTool":{"type":"object","description":"A provider-hosted built-in tool, identified by its versioned type (for example `web_search_20250305`, `code_execution_20250825`, `bash_20250124`, `text_editor_20250124`, or `memory_20250818`).","properties":{"type":{"type":"string"},"name":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","name"]},"ToolChoice":{"description":"Controls how the model selects tools.","oneOf":[{"$ref":"#/components/schemas/ToolChoiceAuto"},{"$ref":"#/components/schemas/ToolChoiceAny"},{"$ref":"#/components/schemas/ToolChoiceTool"},{"$ref":"#/components/schemas/ToolChoiceNone"}],"discriminator":{"propertyName":"type","mapping":{"auto":"#/components/schemas/ToolChoiceAuto","any":"#/components/schemas/ToolChoiceAny","tool":"#/components/schemas/ToolChoiceTool","none":"#/components/schemas/ToolChoiceNone"}}},"ToolChoiceAuto":{"type":"object","properties":{"type":{"type":"string","enum":["auto"]},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type"]},"ToolChoiceAny":{"type":"object","properties":{"type":{"type":"string","enum":["any"]},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type"]},"ToolChoiceTool":{"type":"object","properties":{"type":{"type":"string","enum":["tool"]},"name":{"type":"string"},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type","name"]},"ToolChoiceNone":{"type":"object","properties":{"type":{"type":"string","enum":["none"]}},"required":["type"]},"ThinkingConfig":{"description":"Extended thinking configuration.","oneOf":[{"$ref":"#/components/schemas/EnabledThinkingConfig"},{"$ref":"#/components/schemas/AdaptiveThinkingConfig"},{"$ref":"#/components/schemas/DisabledThinkingConfig"}],"discriminator":{"propertyName":"type","mapping":{"enabled":"#/components/schemas/EnabledThinkingConfig","adaptive":"#/components/schemas/AdaptiveThinkingConfig","disabled":"#/components/schemas/DisabledThinkingConfig"}}},"EnabledThinkingConfig":{"type":"object","description":"Manual thinking budget. Supported by Claude 4.x and older models; Claude 5 models reject this form — use `AdaptiveThinkingConfig` with `output_config.effort` instead.\n","properties":{"type":{"type":"string","enum":["enabled"]},"budget_tokens":{"type":"integer","minimum":1024}},"required":["type","budget_tokens"]},"AdaptiveThinkingConfig":{"type":"object","description":"Adaptive thinking — the model decides how much to think based on the request. Required form for Claude 5 models (which reject `enabled`/`budget_tokens`). Tune the thinking depth with the top-level `output_config.effort` parameter.\n","properties":{"type":{"type":"string","enum":["adaptive"]}},"required":["type"]},"DisabledThinkingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["disabled"]}},"required":["type"]},"OutputConfig":{"type":"object","description":"Output configuration. Controls how much effort the model puts into the response when adaptive thinking is enabled.\n","properties":{"effort":{"type":"string","description":"Effort level applied when `thinking.type` is `adaptive`.","enum":["low","medium","high"]}}},"MessagesResponse":{"type":"object","description":"Anthropic-native non-streaming Messages API response.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["message"]},"role":{"type":"string","enum":["assistant"]},"model":{"type":"string"},"nexos_model_uuid":{"type":"string","description":"The nexos model identifier (company model UUID) used for this response. Same value as the `X-Nexos-Model-Id` response header; can be passed as `model` in subsequent requests. Nexos extension."},"nexos_model_name":{"type":"string","description":"The nexos model name used for this response (the value accepted as `model` in subsequent requests). Nexos extension."},"cost_savings":{"$ref":"#/components/schemas/CostSavings"},"content":{"type":"array","items":{"$ref":"#/components/schemas/ContentBlock"}},"stop_reason":{"type":"string","nullable":true,"enum":["end_turn","max_tokens","stop_sequence","tool_use","pause_turn","refusal"]},"stop_sequence":{"type":"string","nullable":true},"stop_details":{"$ref":"#/components/schemas/StopDetails","nullable":true},"usage":{"$ref":"#/components/schemas/Usage"},"container":{"$ref":"#/components/schemas/Container","nullable":true}},"required":["id","type","role","content","model","usage"]},"CostSavings":{"type":"object","description":"Cost savings for this request, in the same unit as `usage.nexos_credits_cost`.\n`baseline_cost` is what the request would have cost without nexos optimizations; it equals\n`charged_cost` plus every non-null saving. A saving is `null` when its optimization did not\napply to the request, and `0` when it applied but saved nothing. Nexos extension.\n","properties":{"baseline_cost":{"type":"number","format":"double","description":"Cost the request would have had without nexos optimizations."},"charged_cost":{"type":"number","format":"double","description":"Cost actually charged for the request. Same value as `usage.nexos_credits_cost`."},"cache_optimization":{"type":"number","format":"double","nullable":true,"description":"Saving from prompt cache breakpoints injected by the nexos optimizer. Negative when writing the cache cost more than it saved on this request (cache writes are billed above the normal input rate); later cache reads recover it. `null` when the optimizer did not inject cache control."},"nexos_cache":{"type":"number","format":"double","nullable":true,"description":"Saving from serving the response from the nexos response cache. `null` when the response was not served from cache."}},"required":["baseline_cost","charged_cost","cache_optimization","nexos_cache"]},"StopDetails":{"type":"object","description":"Why a turn was refused. Present when `stop_reason` is `refusal`, and null on every\nother stop reason. Anthropic describes a refusal here rather than in a content block,\nso a client should branch on `stop_reason` or `stop_details.type` rather than assume\n`category` and `explanation` are populated.\n","properties":{"type":{"type":"string","enum":["refusal"]},"category":{"type":"string","nullable":true,"description":"The policy category the decline falls under. Null when it maps to no named\ncategory, which is always the case for a refusal translated from another\nprovider — their APIs carry no equivalent category.\n"},"explanation":{"type":"string","nullable":true,"description":"A human-readable description of the decline, such as the refusal text the\nupstream model wrote. Display it rather than parse it.\n"}},"required":["type"]},"Usage":{"type":"object","description":"Token counts reported for the request.","properties":{"input_tokens":{"type":"integer","description":"Number of input tokens charged for the request, not counting any tokens read from cache."},"output_tokens":{"type":"integer"},"cache_creation_input_tokens":{"type":"integer","nullable":true,"description":"Number of input tokens stored into the prompt cache during this request."},"cache_read_input_tokens":{"type":"integer","nullable":true,"description":"Number of input tokens read back from the prompt cache, which are billed at a reduced rate."},"cache_creation":{"$ref":"#/components/schemas/CacheCreation","nullable":true},"output_tokens_details":{"type":"object","nullable":true,"description":"Breakdown of the output tokens.","properties":{"thinking_tokens":{"type":"integer","description":"Number of output tokens used for extended thinking."}}},"service_tier":{"type":"string","nullable":true},"server_tool_use":{"$ref":"#/components/schemas/ServerToolUsage","nullable":true},"nexos_credits_cost":{"type":"number","format":"double","description":"Cost of the request in nexos credits."}},"required":["input_tokens","output_tokens"]},"CacheCreation":{"type":"object","description":"Breakdown of cache-write tokens split by cache lifetime tier.","properties":{"ephemeral_5m_input_tokens":{"type":"integer"},"ephemeral_1h_input_tokens":{"type":"integer"}}},"ServerToolUsage":{"type":"object","description":"Usage counts for each server-side tool, present when those tools ran during the request.","properties":{"web_search_requests":{"type":"integer"}}},"Container":{"type":"object","description":"Details of the execution container, included when the request used server-side code execution.","properties":{"id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}},"required":["id","expires_at"]},"MessagesStreamEvent":{"description":"Anthropic-native Messages API SSE event. Discriminated by `type`. Forwarded byte-for-byte\nfrom the upstream provider — public-api does not transform individual events.\n","oneOf":[{"$ref":"#/components/schemas/MessageStartEvent"},{"$ref":"#/components/schemas/ContentBlockStartEvent"},{"$ref":"#/components/schemas/ContentBlockDeltaEvent"},{"$ref":"#/components/schemas/ContentBlockStopEvent"},{"$ref":"#/components/schemas/MessageDeltaEvent"},{"$ref":"#/components/schemas/MessageStopEvent"},{"$ref":"#/components/schemas/PingEvent"},{"$ref":"#/components/schemas/ErrorEvent"}],"discriminator":{"propertyName":"type","mapping":{"message_start":"#/components/schemas/MessageStartEvent","content_block_start":"#/components/schemas/ContentBlockStartEvent","content_block_delta":"#/components/schemas/ContentBlockDeltaEvent","content_block_stop":"#/components/schemas/ContentBlockStopEvent","message_delta":"#/components/schemas/MessageDeltaEvent","message_stop":"#/components/schemas/MessageStopEvent","ping":"#/components/schemas/PingEvent","error":"#/components/schemas/ErrorEvent"}}},"MessageStartEvent":{"type":"object","properties":{"type":{"type":"string","enum":["message_start"]},"message":{"$ref":"#/components/schemas/MessagesResponse"}},"required":["type","message"]},"ContentBlockStartEvent":{"type":"object","properties":{"type":{"type":"string","enum":["content_block_start"]},"index":{"type":"integer"},"content_block":{"$ref":"#/components/schemas/ContentBlock"}},"required":["type","index","content_block"]},"ContentBlockDeltaEvent":{"type":"object","properties":{"type":{"type":"string","enum":["content_block_delta"]},"index":{"type":"integer"},"delta":{"$ref":"#/components/schemas/ContentBlockDelta"}},"required":["type","index","delta"]},"ContentBlockDelta":{"oneOf":[{"$ref":"#/components/schemas/TextDelta"},{"$ref":"#/components/schemas/InputJsonDelta"},{"$ref":"#/components/schemas/ThinkingDelta"},{"$ref":"#/components/schemas/SignatureDelta"},{"$ref":"#/components/schemas/CitationsDelta"}],"discriminator":{"propertyName":"type","mapping":{"text_delta":"#/components/schemas/TextDelta","input_json_delta":"#/components/schemas/InputJsonDelta","thinking_delta":"#/components/schemas/ThinkingDelta","signature_delta":"#/components/schemas/SignatureDelta","citations_delta":"#/components/schemas/CitationsDelta"}}},"TextDelta":{"type":"object","properties":{"type":{"type":"string","enum":["text_delta"]},"text":{"type":"string"}},"required":["type","text"]},"InputJsonDelta":{"type":"object","properties":{"type":{"type":"string","enum":["input_json_delta"]},"partial_json":{"type":"string"}},"required":["type","partial_json"]},"ThinkingDelta":{"type":"object","properties":{"type":{"type":"string","enum":["thinking_delta"]},"thinking":{"type":"string"}},"required":["type","thinking"]},"SignatureDelta":{"type":"object","properties":{"type":{"type":"string","enum":["signature_delta"]},"signature":{"type":"string"}},"required":["type","signature"]},"CitationsDelta":{"type":"object","properties":{"type":{"type":"string","enum":["citations_delta"]},"citation":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"]}},"required":["type","citation"]},"ContentBlockStopEvent":{"type":"object","properties":{"type":{"type":"string","enum":["content_block_stop"]},"index":{"type":"integer"}},"required":["type","index"]},"MessageDeltaEvent":{"type":"object","properties":{"type":{"type":"string","enum":["message_delta"]},"delta":{"$ref":"#/components/schemas/MessageDelta"},"usage":{"$ref":"#/components/schemas/Usage"},"cost_savings":{"$ref":"#/components/schemas/CostSavings"}},"required":["type","delta","usage"]},"MessageDelta":{"type":"object","description":"Top-level message delta carrying the terminal stop_reason, stop_sequence and — on a\nrefusal — stop_details. A refusal's stop_details arrives here rather than on\nmessage_start, which carries no stop information at all.\n","properties":{"stop_reason":{"type":"string","nullable":true,"enum":["end_turn","max_tokens","stop_sequence","tool_use","pause_turn","refusal"]},"stop_sequence":{"type":"string","nullable":true},"stop_details":{"$ref":"#/components/schemas/StopDetails","nullable":true}}},"MessageStopEvent":{"type":"object","properties":{"type":{"type":"string","enum":["message_stop"]}},"required":["type"]},"PingEvent":{"type":"object","properties":{"type":{"type":"string","enum":["ping"]}},"required":["type"]},"ErrorEvent":{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}},"required":["type","message"]}},"required":["type","error"]}}},"paths":{"/v1/messages":{"post":{"operationId":"createMessage","tags":["Messages"],"summary":"Create a message (Anthropic-native)","description":"Anthropic-native Messages API. Accepts requests in Anthropic's wire format and forwards\nthem to the upstream Anthropic provider byte-for-byte, preserving native features such as\n`cache_control` for prompt caching. Use this endpoint when the client already speaks\nAnthropic — it avoids the OpenAI translation layer that silently strips `cache_control`.\n","parameters":[{"in":"header","name":"X-Session-Id","required":false,"schema":{"type":"string","maxLength":256},"description":"Optional client-provided identifier for grouping requests into a session. Leading and\ntrailing whitespace is trimmed; blank values, values longer than 256 bytes, and values\nwith non-printable or non-ASCII characters are ignored. Takes precedence over\n`X-Claude-Code-Session-Id`, `session-id`, and `thread-id`. When none of these headers has\na usable value, a session fingerprint is derived from the first user message and the\nauthenticated company, user, and team identity, if usable message text is available. This\nheader does not load conversation history.\n"},{"in":"header","name":"X-Claude-Code-Session-Id","required":false,"schema":{"type":"string","maxLength":256},"description":"Alternative client-provided session identifier, supported for Claude Code clients. Used\nonly when `X-Session-Id` has no usable value. Takes precedence over `session-id` and\n`thread-id`. Leading and trailing whitespace is trimmed; blank values, values longer than\n256 bytes, and values with non-printable or non-ASCII characters are ignored. This header\ndoes not load conversation history.\n"},{"in":"header","name":"thread-id","required":false,"schema":{"type":"string","maxLength":256},"description":"Alternative client-provided session identifier, supported for Codex clients. Used only\nwhen none of `X-Session-Id`, `X-Claude-Code-Session-Id`, and `session-id` has a usable\nvalue. Leading and trailing whitespace is trimmed; blank values, values longer than 256\nbytes, and values with non-printable or non-ASCII characters are ignored. This header does\nnot load conversation history.\n"},{"in":"header","name":"session-id","required":false,"schema":{"type":"string","maxLength":256},"description":"Alternative client-provided session identifier, supported for Codex clients, which send\none value for a root thread and all of its subagents. Used only when neither\n`X-Session-Id` nor `X-Claude-Code-Session-Id` has a usable value. Takes precedence over\n`thread-id`. Leading and trailing whitespace is trimmed; blank values, values longer than\n256 bytes, and values with non-printable or non-ASCII characters are ignored. This header\ndoes not load conversation history.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessageRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagesResponse"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/MessagesStreamEvent"}}}}}}}}}
```

## Count message tokens (Anthropic-native)

> Anthropic-native token counting. Accepts the same structured inputs as \`/v1/messages\` and\
> returns the number of input tokens without generating a response. Claude Code calls this as\
> \`/v1/messages/count\_tokens?beta=true\` to size its context window; when the endpoint is\
> missing it falls back to a character-based estimate.<br>

```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Messages","description":"Anthropic-native Messages API for prompt-cache-preserving passthrough."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"CountMessageTokensRequest":{"type":"object","description":"Anthropic-native token counting request body. Accepts the same structured inputs as\n`/v1/messages` — `system`, `messages`, `tools`, `thinking` — but no `max_tokens`, because no\noutput is generated. Forwarded byte-for-byte to the upstream provider.\n","properties":{"model":{"type":"string","description":"Model identifier or alias resolved against the company's configured models. Must resolve to an Anthropic-provider model."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InputMessage"}},"system":{"description":"System prompt as a single string or as an array of text blocks (each may carry `cache_control`).","oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/SystemBlock"}}]},"tools":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"$ref":"#/components/schemas/ToolChoice","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true},"thinking":{"$ref":"#/components/schemas/ThinkingConfig","nullable":true}},"required":["model","messages"]},"InputMessage":{"type":"object","description":"A single input message in the `messages` array.","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"Either a plain string or an array of content blocks.","oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ContentBlock"}}]}},"required":["role","content"]},"ContentBlock":{"description":"A content block within a message's `content` array. Discriminator is `type`.\nStrict-typed concrete subtypes cover the full Anthropic Messages API surface;\n`cache_control` is forwarded byte-for-byte where present.\n","oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"},{"$ref":"#/components/schemas/DocumentBlock"},{"$ref":"#/components/schemas/ToolUseBlock"},{"$ref":"#/components/schemas/ToolResultBlock"},{"$ref":"#/components/schemas/ThinkingBlock"},{"$ref":"#/components/schemas/RedactedThinkingBlock"},{"$ref":"#/components/schemas/ServerToolUseBlock"},{"$ref":"#/components/schemas/WebSearchToolResultBlock"},{"$ref":"#/components/schemas/SearchResultBlock"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TextBlock","image":"#/components/schemas/ImageBlock","document":"#/components/schemas/DocumentBlock","tool_use":"#/components/schemas/ToolUseBlock","tool_result":"#/components/schemas/ToolResultBlock","thinking":"#/components/schemas/ThinkingBlock","redacted_thinking":"#/components/schemas/RedactedThinkingBlock","server_tool_use":"#/components/schemas/ServerToolUseBlock","web_search_tool_result":"#/components/schemas/WebSearchToolResultBlock","search_result":"#/components/schemas/SearchResultBlock"}}},"TextBlock":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true},"citations":{"type":"array","nullable":true,"items":{"type":"object","properties":{"type":{"type":"string"},"cited_text":{"type":"string"},"document_index":{"type":"integer"},"document_title":{"type":"string","nullable":true},"start_char_index":{"type":"integer"},"end_char_index":{"type":"integer"},"start_page_number":{"type":"integer"},"end_page_number":{"type":"integer"},"start_block_index":{"type":"integer"},"end_block_index":{"type":"integer"}},"required":["type"]}}},"required":["type","text"]},"CacheControlEphemeral":{"type":"object","description":"Marks a caching breakpoint for prompt caching. Attach it to any cacheable element —\nsystem text blocks, message content blocks, tool definitions, `tool_use`, `tool_result`,\n`search_result`, or `document` blocks. A request may carry up to four such breakpoints.\nWhen supplied at the top level, it is automatically applied to the last cacheable block.\n","properties":{"type":{"type":"string","enum":["ephemeral"]},"ttl":{"type":"string","description":"How long the cached prefix stays valid. Omitting it falls back to `5m`; `1h` works without any beta header.","enum":["5m","1h"]}},"required":["type"]},"ImageBlock":{"type":"object","properties":{"type":{"type":"string","enum":["image"]},"source":{"$ref":"#/components/schemas/ImageSource"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","source"]},"ImageSource":{"oneOf":[{"$ref":"#/components/schemas/ImageSourceBase64"},{"$ref":"#/components/schemas/ImageSourceURL"}]},"ImageSourceBase64":{"type":"object","properties":{"type":{"type":"string","enum":["base64"]},"media_type":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp"]},"data":{"type":"string","description":"Base64-encoded image bytes."}},"required":["type","media_type","data"]},"ImageSourceURL":{"type":"object","properties":{"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"DocumentBlock":{"type":"object","properties":{"type":{"type":"string","enum":["document"]},"source":{"$ref":"#/components/schemas/DocumentSource"},"title":{"type":"string","nullable":true},"context":{"type":"string","nullable":true},"citations":{"$ref":"#/components/schemas/CitationsConfig","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","source"]},"DocumentSource":{"oneOf":[{"$ref":"#/components/schemas/DocumentSourceBase64"},{"$ref":"#/components/schemas/DocumentSourceURL"},{"$ref":"#/components/schemas/DocumentSourceText"},{"$ref":"#/components/schemas/DocumentSourceContent"}]},"DocumentSourceBase64":{"type":"object","properties":{"type":{"type":"string","enum":["base64"]},"media_type":{"type":"string","enum":["application/pdf"]},"data":{"type":"string"}},"required":["type","media_type","data"]},"DocumentSourceURL":{"type":"object","properties":{"type":{"type":"string","enum":["url"]},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"DocumentSourceText":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"media_type":{"type":"string","enum":["text/plain"]},"data":{"type":"string"}},"required":["type","media_type","data"]},"DocumentSourceContent":{"type":"object","properties":{"type":{"type":"string","enum":["content"]},"content":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"}]}}},"required":["type","content"]},"CitationsConfig":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"ToolUseBlock":{"type":"object","properties":{"type":{"type":"string","enum":["tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object","description":"Arguments passed to the tool, matching the input schema the client declared for it."},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","id","name","input"]},"ToolResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"tool_use_id":{"type":"string"},"content":{"description":"Either a plain string or an array of text/image content blocks.","oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/TextBlock"},{"$ref":"#/components/schemas/ImageBlock"}]}}]},"is_error":{"type":"boolean","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","tool_use_id"]},"ThinkingBlock":{"type":"object","properties":{"type":{"type":"string","enum":["thinking"]},"thinking":{"type":"string"},"signature":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","thinking","signature"]},"RedactedThinkingBlock":{"type":"object","properties":{"type":{"type":"string","enum":["redacted_thinking"]},"data":{"type":"string"}},"required":["type","data"]},"ServerToolUseBlock":{"type":"object","description":"A built-in tool call (such as `web_search` or `code_execution`) that the provider runs on its own side.","properties":{"type":{"type":"string","enum":["server_tool_use"]},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","id","name","input"]},"WebSearchToolResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["web_search_tool_result"]},"tool_use_id":{"type":"string"},"content":{"description":"Either an array of search results or an error block.","oneOf":[{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["web_search_result"]},"url":{"type":"string"},"title":{"type":"string"},"encrypted_content":{"type":"string"},"page_age":{"type":"string","nullable":true}},"required":["type","url","title","encrypted_content"]}},{"type":"object","properties":{"type":{"type":"string","enum":["web_search_tool_result_error"]},"error_code":{"type":"string"}},"required":["type","error_code"]}]},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","tool_use_id","content"]},"SearchResultBlock":{"type":"object","properties":{"type":{"type":"string","enum":["search_result"]},"source":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"content":{"type":"array","items":{"$ref":"#/components/schemas/TextBlock"}},"citations":{"$ref":"#/components/schemas/CitationsConfig","nullable":true},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","content"]},"SystemBlock":{"type":"object","description":"A system prompt content block. Supports `cache_control` for caching the system prefix.","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","text"]},"Tool":{"description":"Tool definition. Either a custom tool (function with input_schema) or a built-in server tool (typed by versioned `type`).","oneOf":[{"$ref":"#/components/schemas/CustomTool"},{"$ref":"#/components/schemas/ServerTool"}]},"CustomTool":{"type":"object","description":"A function tool that the client defines and implements.","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","description":"A JSON Schema object that defines the shape of the tool's input arguments."},"type":{"type":"string","enum":["custom"],"description":"Optional type marker. Leave it out for legacy custom tools, or set it to `custom` when you need to be explicit."},"strict":{"type":"boolean","description":"Whether to enforce strict schema adherence for this tool's input. Requires `additionalProperties: false` and every property listed in `required` on `input_schema`. Omitted leaves the provider's own default.\n"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["name","input_schema"]},"ServerTool":{"type":"object","description":"A provider-hosted built-in tool, identified by its versioned type (for example `web_search_20250305`, `code_execution_20250825`, `bash_20250124`, `text_editor_20250124`, or `memory_20250818`).","properties":{"type":{"type":"string"},"name":{"type":"string"},"cache_control":{"$ref":"#/components/schemas/CacheControlEphemeral","nullable":true}},"required":["type","name"]},"ToolChoice":{"description":"Controls how the model selects tools.","oneOf":[{"$ref":"#/components/schemas/ToolChoiceAuto"},{"$ref":"#/components/schemas/ToolChoiceAny"},{"$ref":"#/components/schemas/ToolChoiceTool"},{"$ref":"#/components/schemas/ToolChoiceNone"}],"discriminator":{"propertyName":"type","mapping":{"auto":"#/components/schemas/ToolChoiceAuto","any":"#/components/schemas/ToolChoiceAny","tool":"#/components/schemas/ToolChoiceTool","none":"#/components/schemas/ToolChoiceNone"}}},"ToolChoiceAuto":{"type":"object","properties":{"type":{"type":"string","enum":["auto"]},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type"]},"ToolChoiceAny":{"type":"object","properties":{"type":{"type":"string","enum":["any"]},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type"]},"ToolChoiceTool":{"type":"object","properties":{"type":{"type":"string","enum":["tool"]},"name":{"type":"string"},"disable_parallel_tool_use":{"type":"boolean","nullable":true}},"required":["type","name"]},"ToolChoiceNone":{"type":"object","properties":{"type":{"type":"string","enum":["none"]}},"required":["type"]},"ThinkingConfig":{"description":"Extended thinking configuration.","oneOf":[{"$ref":"#/components/schemas/EnabledThinkingConfig"},{"$ref":"#/components/schemas/AdaptiveThinkingConfig"},{"$ref":"#/components/schemas/DisabledThinkingConfig"}],"discriminator":{"propertyName":"type","mapping":{"enabled":"#/components/schemas/EnabledThinkingConfig","adaptive":"#/components/schemas/AdaptiveThinkingConfig","disabled":"#/components/schemas/DisabledThinkingConfig"}}},"EnabledThinkingConfig":{"type":"object","description":"Manual thinking budget. Supported by Claude 4.x and older models; Claude 5 models reject this form — use `AdaptiveThinkingConfig` with `output_config.effort` instead.\n","properties":{"type":{"type":"string","enum":["enabled"]},"budget_tokens":{"type":"integer","minimum":1024}},"required":["type","budget_tokens"]},"AdaptiveThinkingConfig":{"type":"object","description":"Adaptive thinking — the model decides how much to think based on the request. Required form for Claude 5 models (which reject `enabled`/`budget_tokens`). Tune the thinking depth with the top-level `output_config.effort` parameter.\n","properties":{"type":{"type":"string","enum":["adaptive"]}},"required":["type"]},"DisabledThinkingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["disabled"]}},"required":["type"]},"CountMessageTokensResponse":{"type":"object","description":"Number of input tokens the supplied request would consume.","properties":{"input_tokens":{"type":"integer","description":"Estimated total input tokens. The count is an estimate and is not billed."}},"required":["input_tokens"]}}},"paths":{"/v1/messages/count_tokens":{"post":{"operationId":"countMessageTokens","tags":["Messages"],"summary":"Count message tokens (Anthropic-native)","description":"Anthropic-native token counting. Accepts the same structured inputs as `/v1/messages` and\nreturns the number of input tokens without generating a response. Claude Code calls this as\n`/v1/messages/count_tokens?beta=true` to size its context window; when the endpoint is\nmissing it falls back to a character-based estimate.\n","parameters":[{"in":"query","name":"beta","schema":{"type":"string"},"required":false,"description":"Marks the request as using the Anthropic beta API surface. Claude Code sends `beta=true`;\nforwarded upstream unchanged.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountMessageTokensRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountMessageTokensResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexos.ai/gateway-api/messages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.