Messages

Create conversational turns using the native Anthropic Messages API wire format across Claude and cloud providers with prompt caching and cost tracking.

The /v1/messages endpoint provides direct compatibility with the native Anthropic Messages API wire format across Claude and cloud providers. Send existing Claude SDK payloads to the Claude models nRouter serves, with configurable fallback chains, prompt caching telemetry, and exact list pricing. See the Anthropic Messages API documentation.

Preflight evaluates key ACLs, rate limits (RPM/TPM), content inspection, and token reservations (x-nr-guardrails: blocked returns HTTP 400 with $0 spent and $0 held). Native Anthropic SSE streaming, caching metrics, and thinking blocks are preserved; fallbacks trigger only when configured (Router Settings or nrouter_fallbacks).

POST https://api.nrouter.ai/v1/messages

Request Parameters

Parameter	Type	Required	Default	Description
`model`	`string`	Yes	—	Target Claude model (e.g. `claude-sonnet-4-5-20250929`).
`messages`	`array`	Yes	—	Input messages containing `role` (`user` or `assistant`) and `content`.
`max_tokens`	`integer`	Yes	—	Maximum number of tokens to generate.
`system`	`string` or `array`	No	—	System prompt string or array of text blocks supporting cache controls.
`metadata`	`object`	No	—	Request metadata object (e.g. `user_id`).
`stop_sequences`	`string[]`	No	—	Custom sequences halting token generation.
`stream`	`boolean`	No	`false`	When true, streams chunks via Server-Sent Events (SSE).
`temperature`	`number`	No	`1.0`	Sampling randomness between `0.0` and `1.0`.
`top_p`	`number`	No	—	Nucleus sampling cutoff threshold.
`top_k`	`integer`	No	—	Sample from top K options for each token.
`tools`	`array`	No	—	Tool definitions available to the model.
`tool_choice`	`object`	No	`{"type": "auto"}`	Tool use configuration (`auto`, `any`, `tool`).
`thinking`	`object`	No	—	Extended thinking mode configuration.
`nrouter_fallbacks`	`string[]`	No	—	1–4 fallback models if primary provider admission fails.
`nrouter_guardrails`	`string[]`	No	—	1–8 organization guardrail policy IDs.
`nrouter_cache`	`boolean`	No	`true`	When `false`, bypasses the response cache.

Examples

import { nRouter } from "@nrouter_ai/sdk";
const client = new nRouter({ apiKey: process.env.NROUTER_API_KEY });
const res = await client.messages.create({
  model: "claude-sonnet-4-5-20250929", max_tokens: 1024, messages: [{ role: "user", content: "Hello!" }],
});
console.log(res.content[0].text, client.lastResponse?.cost);

Headers & Errors

Inbound: Authorization: Bearer sk-nrouter-..., Content-Type: application/json, optional anthropic-version: 2023-06-01, x-nr-tags. Telemetry: x-nr-request-id, x-nr-latency-ms, x-nr-request-cost, x-nr-model, x-nr-routing, x-nr-attempts, x-nr-guardrails, x-nr-cache-read-tokens, x-nr-cache-write-tokens. See Chat Completions.

HTTP Status	Error Code	Reason
400 Bad Request	`invalid_request`	Missing required `max_tokens` or `messages` field.
400 Bad Request	`guardrail_blocked`	Preflight inspection detected prompt injection or safety policy violation.
401 Unauthorized	`invalid_api_key`	Virtual key missing, expired, or invalid.
402 Payment Required	`insufficient_credits`	Organization balance insufficient to reserve token hold.
404 Not Found	`model_not_found`	Model identifier not found or unauthorized for tenant.
429 Too Many Requests	`rate_limit_exceeded`	RPM or TPM ceiling crossed; check `x-nr-limit-source`.
500 / 503 Provider Error	`service_unavailable`	Upstream outage. 503 triggers fallback only if configured (`nrouter_fallbacks`).

Authorization

NRouterApiKey

AuthorizationBearer <token>

Your nRouter virtual key (sk-nrouter-…). Sent as Authorization: Bearer sk-nrouter-….

In: header

Header Parameters

x-nr-compress?string

Request prompt compression: on to compress eligible prompts, off to skip

Value in

"on"
"off"

x-nr-tags?string

Custom spend and attribution tags (comma-separated key=value pairs)

x-nr-mcp-server?string

Target MCP server ID when routing MCP tool calls or prompts through the gateway

x-nr-client-language?string

Caller SDK runtime language identification (e.g. typescript, python, rust, go)

x-nr-session-id?string

Caller session identifier allowed at edge for grouping related client turns

x-nr-trace?string

Inbound trace detail level override for request lifecycle spans

Value in

"off"
"stages"
"verbose"

x-nr-trace-stages?string

Inbound stage-level trace emission override

Value in

"off"
"stages"
"verbose"

x-nr-trace-id?string

Accepted so a client sending it is not refused; the value is not recorded and not propagated. Every response carries the gateway's own trace ID in this header, never the one sent.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Model id (see GET /v1/models).

messages*array<>

max_tokens*integer

Range1 <= value

system?|array<>

System prompt string or array of Anthropic content blocks (including cache_control).

temperature?number

Range0 <= value <= 1

top_p?number

Range0 <= value <= 1

top_k?integer

Range1 <= value

stop_sequences?array<string>

stream?boolean

Defaultfalse

metadata?

Anthropic request metadata (e.g. user_id).

tools?array<>

Anthropic tool definitions (input_schema).

tool_choice?

Anthropic tool selection mode (auto, any, tool, none).

thinking?

Extended thinking configuration for reasoning-capable models.

nrouter_cache?boolean

Use nRouter's tenant-isolated response cache for buffered text requests. Set false to force provider egress; streams are never cached.

Defaulttrue

nrouter_prompt_template_id?string

Tenant-scoped managed prompt template. The gateway selects its production-pinned version, or the active version when no pin exists.

Formatuuid

nrouter_prompt_variables?

Scalar variables rendered into the managed prompt. Authenticated system variables override conflicting caller values.

nrouter_fallbacks?array<string>

Optional list of up to 4 model names tried in order after the model named in the request, only on an upstream 429, 503 or Anthropic 529, or a connection failure. Replaces the fallback list the organization saved for that model for this call. On nrouter/auto it replaces the fallbacks nrouter/auto would choose (its chosen model is tried first, then these), and an empty list means no fallback; an empty list on any other model is refused.

Items0 <= items <= 4

nrouter_optimize?string

nrouter/auto only: the selection strategy for this one request, overriding the organization's Router Settings strategy. "quality" serves the best model for the task; "cost" serves the lowest list rate among the models fit for the task. Any other value, or the field on another model, is refused with 400 invalid_request.

Value in

"quality"
"cost"

nrouter_guardrails?array<string>

Optional list of guardrail policy IDs or names to enforce for this request.

nrouter_web_search?boolean

Enable gateway-augmented web search grounding.

nrouter_tags?

Custom key-value metadata tags recorded in SpendLogs and trace metadata for cost attribution.

Response Body

`application/json`

curl -X POST "https://example.com/v1/messages" \  -H "Content-Type: application/json" \  -d '{    "model": "claude-sonnet-4-5-20250929",    "max_tokens": 1024,    "messages": [      {        "role": "user",        "content": "Explain multi-tenant credit reservation."      }    ]  }'

{  "id": "msg_01",  "type": "message",  "role": "assistant",  "content": [    {      "type": "text",      "text": "Hello!"    }  ],  "usage": {    "input_tokens": 9,    "output_tokens": 3  }}

Request Parameters

Examples

Headers & Errors

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

404application/json

405application/json

413application/json

415application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`