Getting started with the Nautili AI Gateway: from key to first request
Issue an sk-dz- runtime key, point the OpenAI and Anthropic SDKs at your gateway with a base-URL swap, send three requests and find each one in Traces.
8 min readLast reviewed October 19, 2026Verified against gateway contract 0.6.0 (openapi.yaml) and nt 0.0.4
What you’ll have at the end
By the end you will have an issued sk-dz- key and three requests served through your gateway on the OpenAI and Anthropic SDKs, with nothing changed but a base URL and a key. Each request will be visible in the Nautili dashboard.
Three components take part in every request. The gateway sits in your request path: it resolves the model and the key, checks the caches, forwards to the provider and records the outcome. The control plane decides whether the request may spend, which routing profile applies and which credential forwards; the gateway caches each answer behind a freshness window.
The Nautili dashboard is where you see the result. Keys, guardrails and routing profiles are edited there, and every keyed request lands in Traces under Usage.
There are four ways in; this guide takes the first two.
| Path | What you change | Read |
|---|---|---|
| PathIssued key + your own HTTP code | What you changeAuthorization: Bearer sk-dz-... to /v1/chat/completions, /v1/responses or /v1/messages. | ReadAPI access |
| PathVendor SDK base-URL swap | What you changeKeep the openai or anthropic package; set base_url and api_key. | ReadSDKs |
| PathCoding tools on your subscription | What you changePoint Claude Code, Codex or Cursor at the gateway; your seat keeps paying. Needs a Proxy Gateway (self-hosted or DevZero-hosted); the Shared Gateway serves sk-dz- keys only. | ReadConnect coding tools |
PathThe nt terminal client | What you changecurl -fsSL https://nautili.ai/install.sh | bash, then nt login. | ReadDownload |
Before you begin
- A Nautili account. A new account opens on the Demo tier with a free starter credit on the Shared Gateway; add credits to move to Pay-as-you-go.
- A gateway you can reach. Its base URL is shown on the API keys screen under Access. This guide writes it as
https://<your-gateway-host>. - A team with a forwarding credential on Provider keys, or enrolled in DevZero-managed custody.
pip install openai anthropic, ornpm install openai @anthropic-ai/sdk, andcurl.- Model ids are always
author/slug; this guide usesanthropic/claude-haiku-4.5.
Step 1: Issue a runtime key
Open API keys under Access and choose Advanced, which opens the Issue sk-dz key modal. Leave Kind as Runtime (inference traffic), name it, pick an owner (or none, for a service key) and choose a custody.

The plaintext token, sk-dz- plus 43 base62 characters, is shown exactly once; only its hash is stored, so copy it now and export it as NAUTILI_KEY.
Custody decides whose provider credential pays when this key forwards: managed uses DevZero's provisioned credential and fails closed, byok uses your own and fails closed, and Auto (unbound) uses yours when the team has one, else DevZero's. Scopes (keys:read, keys:write, usage:read, models:read) apply only to management keys for /api/v1; a runtime key carries none.
Step 2: Send a chat completion through the OpenAI SDK
The OpenAI-shape client takes the base URL with /v1 appended.
The gateway gates the decided model, checks the caches, forwards with the resolved credential and returns the upstream's Chat Completions response unchanged in shape.
Step 3: Send a message through the Anthropic SDK
The Anthropic client appends /v1/messages itself, so its base URL carries no /v1. On the Shared Gateway, every team's default, it is the same hostname as the OpenAI-compatible surface, https://shared.gateway.nautili.ai; on a DevZero-hosted gateway it is the anthropic- prefixed hostname; self-hosted, it is listener port 8081 unless the chart's ingress derives that hostname. The API keys screen prints the exact Anthropic base URL for your team next to the OpenAI one. The issued key goes in api_key, sent as x-api-key.
The same key, X-Dz-* headers and dz_router semantics apply on this wire, and cache_control breakpoints pass through untouched.
Step 4: Send a Responses API request
/v1/responses uses the same OpenAI-shape client as Step 2.
The gateway returns the upstream's Responses-API response unchanged in shape.
Verify
The Step 2 curl with -i prints headers first. Trimmed to the two the gateway adds and the fields that matter:
X-Dz-Request-Id is the id the trace row is stored under. X-Cache is stamped MISS before the cache is consulted and overwritten with HIT when the exact cache serves the request.
Open Traces under Usage. Each request is a row with its model, endpoint, status, cache outcome, tokens and cost. Open the row: when a routing profile chose the path, Router attempts lists the decided model and, when a fallback moved it, the model that served and the custody arm that was charged. Send the same body twice and the second row shows a cache hit.
Because every request carried X-Dz-Session-Id: quickstart-1, the row's Session column and the Open session button in the detail panel link all three into one session. A client-supplied session id is the only stable session key, and it is what makes routing pins work across turns.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
Error400 invalid_model_id | Causemodel is malformed, or a bare name the catalog does not resolve, such as gpt-4o. (A bare Claude name such as claude-haiku-4-5 is mapped to its catalog id and is fine.) | FixUse author/slug: anthropic/claude-haiku-4.5. |
Error401 with invalid_api_key (OpenAI envelope) or authentication_error (Anthropic envelope) | CauseThe key is revoked, disabled, expired or mistyped, or no sk-dz- key was sent. | FixIssue a new key on API keys; an old plaintext cannot be recovered. |
Error400 no_default_model | CauseThe request named no model and no rung of the profile ladder configures one. | FixAlways send model. |
Error400 auto_not_enabled | Causemodel was auto but no profile rung enables auto mode. | FixName a model, or enable auto in the team's routing profile. |
Error429 insufficient_quota with x-should-retry: false | CauseA budget guardrail in enforce mode reached its ceiling for the window (400 on the Anthropic surface). | FixRaise the limit or wait for the reset; the SDK will not retry it. |
Next steps
- Govern LLM traffic with guardrails, to put a budget, rate ceiling or model allowlist on this key.
- Routing profiles, fallbacks and overrides, to set fallback chains and provider preferences server-side.
- Your first model trial, to test a cheaper candidate model on a sample of this traffic before you switch.
- SDKs and Request headers, for the first-party TypeScript provider and the attribution headers that put spend on the right user, project and environment.