DEV Community

nRouter
nRouter

Posted on

No SDK, no wrapper: what nRouter's cURL examples say about the gateway

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!"}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

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
  }'
Enter fullscreen mode Exit fullscreen mode

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-model and x-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-ms and x-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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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)