Skip to main content
POST
Pass-through to Anthropic’s Messages API. Requests to /v1/messages are automatically routed to Anthropic. Use your Anthropic SDK with base_url set to https://gateway.toolken.ai — the SDK appends /v1/messages automatically.

Headers

X-Toolken-Key
string
required
Your Toolken API key. Validated by the gateway and stripped before forwarding.
x-api-key
string
required
Your Anthropic API key (e.g. sk-ant-api03-...). The Anthropic SDK injects this header automatically. Forwarded verbatim by the gateway, never stored.
X-Toolken-Metadata
string
Primary attribution channel. JSON object of key-value pairs (e.g. {"agent":"research-agent","customer_id":"cust_abc"}). Each key becomes a groupable dimension in the dashboard.
X-Toolken-Metadata-*
string
Flat-header shorthand. X-Toolken-Metadata-Agent: research-agent writes metadata key agent. Equivalent to sending the same key in X-Toolken-Metadata.
X-Toolken-Metadata-Feature
string
Sets the feature metadata key. Use to group costs by agent name, workflow, UI surface, or job type.
X-Toolken-Metadata-Customer-Id
string
Sets the customer_id metadata key. Use to attribute costs to an end-customer, org slug, or account ID.

Body

model
string
required
Anthropic model identifier. Must begin with claude- (e.g. claude-opus-4-5).
messages
array
required
Conversation turns. Follows the standard Anthropic Messages schema. Each item has role (user or assistant) and content.
max_tokens
integer
required
Maximum tokens to generate. Required by Anthropic. The gateway enforces an upper cap configured per workspace.
system
string
System prompt. Forwarded verbatim to Anthropic.
stream
boolean
If true, the gateway streams Server-Sent Events back from Anthropic.

Response

id
string
Unique message ID (e.g. msg_abc123).
type
string
Always message.
role
string
Always assistant.
model
string
The Anthropic model that produced the response.
content
array
Array of content blocks. Each block has type (e.g. text) and text.
stop_reason
string
Reason generation stopped (e.g. end_turn).
usage
object
Token counts: input_tokens and output_tokens.