This is the scannable reference: endpoints, authentication, rate limits, error codes, webhooks, and the OpenAPI spec — on one page. NemoRouter speaks the OpenAI REST API, so the request and response shapes are exactly what your SDK already sends.
The contract at a glance
Drop-in /v1/chat/completions, /embeddings, /models
One virtual key — sk-nemo-…
https://api.nemorouter.ai/v1
Cost, latency, guardrails — on every response
This page is a quick-reference overview. The full documentation carries per-endpoint request/response schemas and guides.
These snippets are generated from the canonical NemoRouter SDK examples — the same source the playground and dashboard keys page use. Set NEMOROUTER_API_KEY in your environment and run.
pip install nemoroutersdk| 1 | # Cache: enabled (org default). Pass nemo_cache: false to skip. |
| 2 | from nemoroutersdk import NemoRouter, NemoGuardrailBlockedError |
| 3 | |
| 4 | client = NemoRouter() # reads NEMOROUTER_API_KEY from env |
| 5 | |
| 6 | try: |
| 7 | response = client.chat.completions.create( |
| 8 | model="gemini-2.5-flash", |
| 9 | temperature=1, |
| 10 | max_tokens=1024, |
| 11 | top_p=1, |
| 12 | messages=[ |
| 13 | {"role": "user", "content": "Hello! What models do you support?"}, |
| 14 | ], |
| 15 | # nemo_cache=False, # Uncomment to skip cache |
| 16 | ) |
| 17 | print(response.choices[0].message.content) |
| 18 | |
| 19 | # Auto-captured metadata |
| 20 | meta = client.last_response |
| 21 | if meta: |
| 22 | print(f"Cost: ${meta.cost}") |
| 23 | print(f"Guardrails: {meta.guardrails_applied}") |
| 24 | |
| 25 | except NemoGuardrailBlockedError as e: |
| 26 | print(f"Blocked by guardrail: {e}") |
Point any OpenAI SDK at the Nemo Router endpoint. Set NEMOROUTER_API_KEY in your environment before running.
Base URL is always https://api.nemorouter.ai/v1. Works with the official OpenAI SDKs and any OpenAI-compatible client.
Every LLM request authenticates with a NemoRouter virtual key (sk-nemo-…) in the Authorization header. There are no provider keys to manage — NemoRouter holds those — and no master key ever leaves a trusted service.
Pass your virtual key as a bearer token. This is the only credential your application ever holds.
Authorization: Bearer sk-nemo-xxxxxxxxxxxxNemoRouter is a managed gateway: it owns the OpenAI, Anthropic, and Google credentials. You never see them, never rotate them, and never risk leaking them.
The inference surface is OpenAI-compatible — same paths, same payloads. Models and usage endpoints are NemoRouter additions for catalog discovery and spend visibility.
The OpenAI-compatible inference surface. Chat completions is the primary endpoint and runs the full feature path — guardrails, prompts, A/B tests, caching.
/v1/chat/completionschat.completions.create()/v1/completionscompletions.create()/v1/embeddingsembeddings.create()/v1/images/generationsimages.generate()/v1/audio/speechaudio.speech.create()/v1/audio/transcriptionsaudio.transcriptions.create()Discover the live catalog. Both endpoints are cache-aware, so listing models is cheap to poll from your app.
/v1/modelsmodels.list()/v1/models/{model_id}models.retrieve()/api/models/pricingGET /api/models/pricingRead your credit balance and spend history. Cost is authoritative — the routing engine owns it and surfaces it on the x-nemo-request-cost header.
/api/credits/balanceGET /api/credits/balance/api/credits/historyGET /api/credits/history/nemo/guardrail/logsGET /nemo/guardrail/logsFiles, fine-tuning, batches, and the Assistants API are not yet available through NemoRouter — use chat.completions.create() for now. The docs track the full supported list.
Beyond the standard OpenAI body, NemoRouter attaches headers describing what happened on the gateway — cost, latency, which guardrails ran, which prompt version and A/B variant were used.
| Header | Description | Present |
|---|---|---|
x-nemo-request-id | Unique request ID — quote it in any support ticket. | Always |
x-nemo-latency-ms | Server-side latency in milliseconds. | Always |
x-nemo-request-cost | Exact request cost in USD — authoritative. | When applicable |
x-nemo-guardrails-applied | Guardrails that ran on this request (CSV). | When applicable |
x-nemo-prompt-version | Prompt template version injected, if any. | When applicable |
x-nemo-ab-test | A/B test variant selected for this request. | When applicable |
x-nemo-cache | Cache hit/miss on the models endpoint. | When applicable |
Cost tracking is authoritative — the routing engine owns it and NemoRouter reads it back; we never re-estimate cost ourselves.
Rate limits and throughput are the only differentiators between plans. All features are free on every tier.
| Plan tier | RPM | TPM | TPS |
|---|---|---|---|
| Tier 1 — Pay As You Go | 500 | 500K | 10 |
| Tier 2 — Monthly | 500 | 500K | 50 |
| Tier 3 — Annual | 1K | 1M | 200 |
| Enterprise | Custom | Custom | Custom |
RPM, TPM, and per-key budgets are enforced at the gateway. Spread load across keys, or scale a single key up by moving tiers.
Exceed RPM or TPM and the gateway returns 429 with a NemoRateLimitError — retry after a short backoff.
NemoRouter raises a small, typed family of errors for gateway-specific conditions, on top of the standard OpenAI HTTP status codes. Catch the class, read the code, branch accordingly.
| HTTP | Code / class | What it means |
|---|---|---|
| 400 | guardrail_blockedNemoGuardrailBlockedError | A guardrail blocked the request — e.g. detected PII, a prompt-injection attempt, or a secret in the payload. |
| 402 | insufficient_creditsNemoCreditError | The key would breach its credit balance or budget. No partial debit occurs — the reservation is released cleanly. |
| 429 | rate_limit_exceededNemoRateLimitError | The requests-per-minute (RPM) ceiling for the key or tier was exceeded. Retry after a short backoff. |
| 429 | tpm_limit_exceededNemoRateLimitError | The tokens-per-minute (TPM) ceiling was exceeded. Lower request size or spread load across the window. |
| 503 | credit_check_failedNemoServiceError | The credit system was briefly unavailable. The request is rejected rather than run un-metered — fail-safe by design. |
Bad Request
The request was malformed or missing required parameters.
Authentication Error
Invalid or missing API key.
Permission Denied
Your key does not have access to this model or resource.
Not Found
The requested model or endpoint does not exist.
Request Timeout
The LLM provider did not respond in time.
Rate Limit Exceeded
You have exceeded your tokens-per-minute or requests-per-minute limit.
Internal Server Error
An unexpected error occurred in the proxy.
Bad Gateway
The LLM provider returned an invalid response.
Service Unavailable
The LLM provider is temporarily unavailable.
Gateway Timeout
The LLM provider did not respond in time.
A 402 never partially debits credits — the reserve is released cleanly, so a rejected request costs nothing.
NemoRouter pushes operational events to an HTTPS endpoint you control — no polling. Configure webhook and Slack delivery under Observability → Alerts in the dashboard; there is no webhook plumbing to write yourself.
llm.errorA request failed after retries and failover — surfaces provider outages fast.
budget.thresholdA key, team, or org crossed a configured spend threshold.
provider.outageA provider circuit breaker opened — the gateway is failing over.
guardrail.triggeredA guardrail blocked or redacted content — useful for a security channel.
key.created / key.revokedA virtual key changed — pair with the audit trail for compliance.
Events are delivered with retries and backoff. Pair webhooks with the Slack callback to fan critical alerts straight into a channel.
/v1/webhooks management API is not yet available — see the observability overview.The NemoRouter API specification is published as a JSON document — endpoints, response headers, error classes, and the extra_body fields that drive guardrails, prompts, and caching. Download it, or read the source in the open SDK repository.
Download
openapi.json
The full API spec, served from this site. Feed it to your client generator or API tooling.
Source
nemo-router-sdk
The spec is canonical at spec/nemo-sdk-spec.json in the open SDK repo — alongside runnable examples.
The published spec covers the supported surface today. Endpoints that are not yet available are listed explicitly inside the spec under unsupported_endpoints — nothing is implied that the API does not do.
One key · two-line switch
Create a virtual key, point your OpenAI client at the NemoRouter base URL, and ship. The full per-endpoint reference and guides live in the docs.
Test endpoints live in the playground.