Skip to content

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.

PathIssued key + your own HTTP codeWhat you changeAuthorization: Bearer sk-dz-... to /v1/chat/completions, /v1/responses or /v1/messages.ReadAPI access
PathVendor SDK base-URL swapWhat you changeKeep the openai or anthropic package; set base_url and api_key.ReadSDKs
PathCoding tools on your subscriptionWhat 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 clientWhat 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, or npm install openai @anthropic-ai/sdk, and curl.
  • Model ids are always author/slug; this guide uses anthropic/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.

Issue sk-dz key modal on the API keys screen with Kind set to Runtime and Custody set to Auto

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.

curl https://<your-gateway-host>/v1/chat/completions \
-H "Authorization: Bearer $NAUTILI_KEY" \
-H "Content-Type: application/json" \
-H "X-Dz-Session-Id: quickstart-1" \
-d '{
"model": "anthropic/claude-haiku-4.5",
"messages": [{"role": "user", "content": "Say hello from the gateway."}]
}' -i

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.

curl https://<your-anthropic-base-url>/v1/messages \
-H "x-api-key: $NAUTILI_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-H "X-Dz-Session-Id: quickstart-1" \
-d '{
"model": "anthropic/claude-haiku-4.5",
"max_tokens": 256,
"messages": [{"role": "user", "content": "Say hello from the gateway."}]
}' -i

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.

curl https://<your-gateway-host>/v1/responses \
-H "Authorization: Bearer $NAUTILI_KEY" \
-H "Content-Type: application/json" \
-H "X-Dz-Session-Id: quickstart-1" \
-d '{
"model": "anthropic/claude-haiku-4.5",
"input": "Say hello from the gateway."
}' -i

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:

HTTP/2 200
x-dz-request-id: 7c1f0b2e-3d7a-4e4b-9b7e-2f3a1c5d8e90
x-cache: MISS
{
"model": "anthropic/claude-haiku-4.5",
"choices": [
{ "message": { "role": "assistant", "content": "Hello from the gateway." } }
],
"usage": { "prompt_tokens": 14, "completion_tokens": 7 }
}

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

Error400 invalid_model_idCausemodel 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_modelCauseThe request named no model and no rung of the profile ladder configures one.FixAlways send model.
Error400 auto_not_enabledCausemodel 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: falseCauseA 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

Ready to keep going?

Explore the next guide or start routing through Nautili.