Disclosure: I work on nRouter. This post was drafted with AI assistance and reviewed by me before publishing.
Every SDK guide is, underneath, a promise that the raw HTTP is sane. The fastest way to check that promise is to skip the SDK entirely. nRouter's cURL examples page is the one I send people who want to see the contract before they commit to a client library — here's what it actually shows.
The whole setup is one export
export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"
curl https://api.nrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $NROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
That's the integration. Bearer header, JSON body, the OpenAI-shaped response back — choices, finish_reason, and a usage block with the token counts. No -X POST flag, because -d implies it; the page doesn't add ceremony where curl doesn't need it.
The detail worth pausing on: switching providers is editing one string. The examples run on openai/gpt-4o-mini, and the guide's claim is that OpenAI, Anthropic and Google models are all reachable by changing only the model field. When the raw request is this small, "multi-model" stops being a platform feature and becomes a property of the JSON.
Streaming needs one flag, and it's not the one in the JSON
Adding "stream": true to the body is only half of it. The streaming example also passes -N, which disables curl's output buffering:
curl https://api.nrouter.ai/v1/chat/completions \
-N \
-H "Authorization: Bearer $NROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'
Without -N you'll still get the SSE chunks — eventually, in a lump, which defeats the point of watching them arrive. The response is the standard shape: data: lines carrying chat.completion.chunk objects with deltas, an empty-delta chunk with finish_reason: "stop", and a final data: [DONE]. If you've ever debugged a streaming integration by staring at a spinner, this page is the antidote: the stream is observable from a terminal before any client code exists.
-i is the debugging surface
The section I'd make mandatory reading is Response Headers & Telemetry. Add -i and the gateway answers with its working shown:
-
x-nr-request-id— the unique ID for the request, the thing support will ask for -
x-nr-cost-total-usd— the request's cost, as a header -
x-nr-prompt-tokens,x-nr-completion-tokens,x-nr-total-tokens— usage, per header -
x-nr-modelandx-nr-provider— what actually served the request -
x-nr-usage— the same token counts as a JSON object, parseable straight from the headers -
x-nr-upstream-latency-msandx-nr-latency-ms— where the time went
Notice what's in there: which model and provider actually answered, and how much of the latency was upstream versus gateway. When a gateway routes, the gap between "the model I asked for" and "the model that answered" is exactly where trust goes to die. Putting both, plus the request ID, on every response by default is the correct answer to that — and you can verify it with one flag before you've written a line of integration code.
The error example is a real error
Request a model that doesn't exist and the guide shows the actual shape of the failure:
{
"error": {
"code": "model_not_found",
"message": "Model invalid-model-name not found",
"param": "model",
"type": "invalid_request_error"
}
}
A 400 with a machine-readable code, the offending param named, and a type that tells you it's your request that's wrong. Then two checks, in order: verify the model ID and its status, and check that $NROUTER_API_KEY is actually loaded in your shell. That second one sounds trivial until you've lost twenty minutes to a subshell that never inherited the export — everyone has, once.
The page
Full examples, including the complete header output: https://dev.nrouter.ai/docs/sdks/curl
If you evaluate APIs for a living: what's the first raw request you make before you let an SDK into the codebase — and does the vendor's own docs page make it this easy to run?
Top comments (0)