cURL Examples

Execute inference requests against nRouter using cURL from the command line with ready examples for chat completions, SSE streaming, and response headers.

Execute inference requests directly against the nRouter AI gateway (https://api.nrouter.ai/v1) using standard command-line cURL.

Set your virtual API key via NROUTER_API_KEY:

Universal access: Switch between OpenAI, Anthropic, and Google models by modifying only the "model" field.
Gateway telemetry: Inspect request IDs, exact USD pricing, and token counts via HTTP response headers (-i).

Setup

Export your virtual API key in your terminal:

export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"

Chat Completion

Send a standard chat completion request:

curl https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "What is an LLM gateway?"}
    ]
  }'

To switch models, change the "model" parameter (e.g. claude-sonnet-4-5-20250929, gemini-2.5-flash, or gpt-5.5).

Streaming (SSE)

Stream tokens in real-time over Server-Sent Events by setting "stream": true:

curl https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "Write a short poem about APIs."}
    ],
    "stream": true
  }'

Sample output chunk:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Connected"},"finish_reason":null}]}
data: [DONE]

Response Headers & Telemetry

Use -i to view nRouter FinOps and routing response headers:

curl -i https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Gateway response headers:

x-nr-request-id: 3f8b1a90-6c2d-4f1e-9a77-2b5c0d4e8a13
x-nr-model: gpt-5.5
x-nr-cost-status: exact
x-nr-request-cost: 0.000418
x-nr-input-tokens: 12
x-nr-output-tokens: 34
x-nr-total-tokens: 46

Error Handling

Standard HTTP error responses:

Status Code	Cause	Resolution
`401 Unauthorized`	Invalid or missing API key	Verify `$NROUTER_API_KEY` matches an active virtual key.
`402 Payment Required`	Budget or balance exhausted	Add credits or increase key spend limit in Billing.
`429 Too Many Requests`	Rate limit exceeded	Back off and inspect the `Retry-After` header.

Example 401 error payload:

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Next Steps

Python SDK — Python integration guide
Node.js SDK — Node.js integration guide
Chat Completions API — Full API reference
Authentication — API key management