Chat Completions

The /v1/chat/completions endpoint is nRouter's primary text wire. It serves standard OpenAI- and Anthropic-compatible chat requests across six provider clouds—OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, Azure Foundry, and Alibaba US—behind a single unified API key and a single bill.

POST https://api.nrouter.ai/v1/chat/completions

SDK Code Examples

Every request requires your virtual key prefixed with sk-nrouter-. You can use our official branded SDKs, native community packages, or point any standard OpenAI client library at https://api.nrouter.ai/v1.

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

// Reads NROUTER_API_KEY from environment
const client = new nRouter();

// 1. Standard Chat Completion
const completion = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [
    { role: "system", content: "You are a senior systems architect." },
    { role: "user", content: "Explain how prompt-injection defense operates before credit reservation." }
  ],
  max_completion_tokens: 1024,
  temperature: 0.7,
});

console.log(completion.choices[0].message.content);
console.log(`Cost: $${client.lastResponse?.cost ?? "unpriced"}`);
console.log(`Latency: ${client.lastResponse?.latencyMs}ms`);
console.log(`Request ID: ${client.lastResponse?.requestId}`);

// 2. Real-Time Streaming
const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [{ role: "user", content: "List 3 advantages of an LLM gateway." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Streaming & Server-Sent Events (SSE)

When "stream": true is passed, the gateway immediately establishes an HTTP chunked transfer connection and streams Server-Sent Events (SSE) formatted as data: {...} payloads.

data: {"id":"chatcmpl-98a","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-98a","choices":[{"index":0,"delta":{"content":" world"},"finish_reason":null}]}

data: {"id":"chatcmpl-98a","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Router Aliases vs. Pinned Models

nRouter decouples client applications from rigid vendor model strings. What you place in the "model" field determines the routing strategy:

Request Options

Three optional JSON body fields change routing, guardrails, and caching for one call, without touching your organization's configuration. They are nRouter control fields: the Rust gateway reads them and removes them from the body before forwarding, so no provider ever receives a key beginning with nrouter_. Any other nrouter_* key is refused with 400 rather than passed on.

curl -X POST https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "Summarize this incident report in three bullets." }
    ],
    "nrouter_fallbacks": ["claude-sonnet-4-5", "gemini-2.5-pro"],
    "nrouter_guardrails": ["pii-strict"],
    "nrouter_cache": false
  }'

The same three fields work from every nRouter SDK; SDKs that model the request body strictly expose them through an extra_body-style escape hatch.

Refusal codes

Every refusal carries a machine-readable code alongside its message, so a client can branch on it rather than matching prose:

A request refused at any of these points never reaches a provider and costs nothing.

Full narrative reference: Per-Request Options.

Headers Reference

Request Headers (Inbound)

Response Headers (Outbound)

Every response contains accurate telemetry stamped at the gateway edge:

Prompt Compression

Prompt compression is on by default. On a qualified model, a long prompt is shortened before the model reads it, which means the prompt the model reads is rewritten and the answer can differ from the one your original prompt would have produced. You are billed for what the provider bills — the shorter prompt.

It only runs on models nRouter has qualified for compression, and only on parts of the prompt that are long enough to be worth rewriting; every other request is forwarded unchanged. Your latest turn and any system or developer instructions are never compressed.

Every response tells you what happened on x-nr-compression:

Three ways to opt out, from widest to narrowest:

1. Per organization — set prompt compression to Off in Settings → Privacy. An Owner or Organization Admin can change it.
2. Per request — send x-nr-compress: off.
3. Per message or block — add "nrouter_compress": false to that message. This is a per-message field, not a request-level one; to switch a whole request off, use the header.

A virtual key can also be set never to compress, whatever its organization says.

Guardrails & Prompt Injection Defense

Every inference request passes through nRouter's 4-phase preflight gate chain before touching an upstream provider:

1. Phase 1: In-Memory Validation: Validates virtual key hash, model ACLs, and organization status.
2. Phase 2: Rate Limits & Ceilings: Verifies tenant RPM and TPM sliding window ceilings.
3. Phase 3: Content Inspection: Scores the prompt for prompt injection and for the seven moderation categories, concurrently. If a score crosses its threshold, the gateway halts with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Credit Reservation: Only runs after Phase 3 passes. $0 is spent and $0 is held on blocked injection attacks.

{
  "error": {
    "type": "guardrail_blocked",
    "message": "Request blocked by pre-call prompt injection safety policy."
  }
}