Your first deployment

Connect a provider to an existing gateway and check the resolved configuration before saving it. For local installation, follow Quickstart.

Before you start

You need a running gateway, its master key, and a provider API key. Set the gateway address:

export GATEWAY=http://localhost:4000
export MASTER_KEY=replace-with-your-master-key

Known models need no catalogEntry — their capabilities, limits, and pricing already live in the adapter's catalog. Browse src/adapters/<provider>/catalog.json in the repo, and choose a model included in that catalog (e.g. gpt-5.5 for OpenAI).

Dry-run it

POST /admin/deployments/resolve validates and resolves the exact same body a real POST /admin/deployments would use, without saving anything or touching credentials encryption — use it to check the request configuration. It does not contact the provider or verify the API key:

curl -X POST "$GATEWAY/admin/deployments/resolve" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModel": "general",
    "adapterKey": "openai",
    "upstreamModel": "gpt-5.5",
    "credentials": { "apiKey": "sk-..." }
  }'

The response shows source: "catalog" (confirming it recognized the model — no catalogEntry needed), plus the resolved operations and transports. If source comes back "custom" instead, the model isn't in the catalog and you'll need to follow the custom-model path in Creating deployments instead.

Save the deployment

Send the validated body to the create endpoint:

curl -X POST "$GATEWAY/admin/deployments" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModel": "general",
    "adapterKey": "openai",
    "upstreamModel": "gpt-5.5",
    "credentials": { "apiKey": "sk-..." }
  }'

Test the connection

Create a virtual key allowed to call general, then set API_KEY to its returned secret. This request verifies both the gateway configuration and the upstream connection:

curl -X POST "$GATEWAY/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "general", "messages": [{ "role": "user", "content": "Say hi" }] }'

Confirm that the response contains an assistant message. A successful resolve alone does not prove that the provider credentials or model access work.

Next steps

Creating deployments — every provider, custom models, images/embeddings/audio.
Routing — what happens once general has more than one deployment.
Virtual keys — scoped, rate-limited client keys instead of the master key.