Messages

The /v1/messages endpoint provides direct compatibility with the native Anthropic Messages API wire format. It allows applications built for Anthropic Claude models to route seamlessly through nRouter without changing client SDKs or message payload structures. nRouter dynamically routes requests across direct Anthropic APIs, AWS Bedrock, and Google Vertex AI with automated failover, prompt caching telemetry, and zero-markup pricing.

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

Architectural Role & Lifecycle

When a client application submits a request to /v1/messages, nRouter executes a 4-phase preflight lifecycle before dispatching to upstream providers:

1. Phase 1: In-Memory Key Auth & ACLs: Verifies virtual key hash (sk-nrouter-...), tenant organization state, and ensures entitlement for Claude models.
2. Phase 2: Rate Limits & Ceilings: Validates requests-per-minute (RPM) and tokens-per-minute (TPM) sliding window quotas.
3. Phase 3: Content Moderation & Prompt Injection Scoring: Evaluates the input message payload and system prompt against safety classifiers. If prompt injection is detected, the request is halted with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Credit Reservation: Estimates token volume from prompt length plus max_tokens and reserves the credit envelope. Blocked requests incur zero credit hold and zero spend.
5. Multi-Cloud Dispatch & Stream Processing: Sends the request to the lowest-latency active provider cloud. If Anthropic direct returns 529 or 429, nRouter automatically shifts execution to Bedrock or Vertex AI. For streams, Server-Sent Events (SSE) format is preserved, and exact token spend is settled atomically at end-of-stream.

Request Parameters

The request body must be a JSON object complying with the Anthropic Messages specification:

Response Payloads

Standard Messages Response

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEE",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "nRouter provides seamless multi-cloud routing across Claude models with automated failover."
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 19,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const response = await client.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  system: "You are an expert distributed systems engineer.",
  messages: [
    { role: "user", content: "Explain how multi-cloud failover ensures 99.99% gateway availability." }
  ],
});

console.log(response.content[0].text);
console.log(`Cost: \$${client.lastResponse?.cost}`);

Error Codes & Failure Modes

{
  "error": {
    "type": "gateway_error",
    "message": "max_tokens: field required",
    "code": "invalid_request"
  }
}

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  }}