Adding models

Two ways to add

In the web app, open /models and click Add model. You'll be asked which kind you're adding:

• Add an API key: bring your own provider account (BYOK). Find a model in the catalog and paste the key it needs. Part of the Pro plan for a first connection (teams connected before September 10, 2026 keep full access).
• Add a local model: register an OpenAI-compatible server your organization runs. A Pro feature.

On a model's own page, the waterfall's Add a way offers a third path too, Serve it yourself, for routing that model through a custom endpoint you control (see below). A Pro feature.

Bring your own key

A BYOK route serves a catalog model on your own provider account: you connect the provider's key once, and that model gains a customer_managed pass-through route the gateway can use. The provider bills you directly and the gateway adds no markup. A first connection requires Pro; organizations that already have a provider connection can add and manage accounts without a new plan gate.

The fastest path is Add model → Add an API key: search the catalog, pick the model, and you land on its page with the key form open. List existing accounts first, then create a new account with POST and an explicit, unique setup_alias. Never overwrite an existing account to connect another key. A 409 account_exists means choose another name, not switch to PUT. The save response includes check.status; report its remediation if not valid. Keys are write-only. Reads never return secret material, only the last four characters.

# List first; choose an unused setup_alias across all providers.
curl --fail-with-body "https://api-pr-74.preview.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections" \
  -H "Authorization: Bearer $EXPLABS_API_KEY" || exit 1

# Replace openai-work with your chosen name. 409: choose another name.
curl --fail-with-body -X POST "https://api-pr-74.preview.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections/openai" \
  -H "Authorization: Bearer $EXPLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setup_alias": "openai-work", "secret": "sk-...", "config": {}}'
# Read check.status and any spend_error in the response. Do not repeat POST on a partial save.

Each provider is connected differently:

Multiple provider accounts

Open a provider in Settings → Connections. The same popup on a model's key flow lets you switch between saved accounts or choose Add account. Give each account a unique name. For Azure, save the resource's own key, endpoint and deployment map. Adding a second resource leaves the first resource unchanged.

On a model, choose a saved account and press Use this accountto save it in that model's waterfall. The chooser shows account selection and Add account directly, even when you have only one saved key. Creating an account returns here so you can choose to use it. Merely changing the popup's selection does not change routing. Other fallback routes keep their order. An account restricted to fallback use shows Use as fallback and keeps the primary route. Rotate, disconnect, balance updates and Azure deployment checks apply only to the selected account.

API callers add an account with POST /api/orgs/{org_id}/provider-connections/azure_openaiand {"setup_alias":"azure-secondary","secret":"YOUR_AZURE_KEY","config":{"endpoint":"https://second-resource.openai.azure.com","api_version":"v1","deployments":{"gpt-4o-mini":"my-deployment"}}}. POST refuses an existing name with 409 account_exists; it never rotates that account. Names are unique across providers in the organization. Use PUT with the saved setup_aliasonly when deliberately replacing that account's key and configuration. If an optional admin-key write fails after the serving key is saved, the API still returns the saved connection with spend_error and instructions to retry with PUT and the same returned alias, serving secret and config, not POST. An inference key belongs in secret; an OpenAI or Anthropic admin key belongs only in spend_secret. Reads never return the key. Saving an account does not add arbitrary models to the catalog; select it on the eligible model's waterfall.

Pass ?setup_alias=azure-secondary to account checks, spend refreshes and disconnects. An Azure deployment-check body also accepts setup_alias. To choose an account for a model through the API, read the model detail's BYOK lane IDs, then save the complete ordered list to PUT /api/models/{slug}/waterfall. Use the returned lane IDs, never an Azure resource ID or key as a routing selector.

Local model

A local model is your own OpenAI-compatible server (a self-hosted vLLM box, a lab server) registered as an ordinary catalog row scoped to your org: one model plus a local deployment pointing at your server's base_url. It becomes callable by slug just like a hosted model, private to your organization, with identical telemetry. Adding a local model is a Pro feature.

In the app, use Add model → Add a local model. Set a name, the base URL, and the model id your server expects. The Supported parameters you check (temperature, tools, reasoning, response format, structured outputs) are recorded on the route, so the gateway accepts exactly those fields and rejects the rest. Declare what your server actually supports. If your server requires a key, pass endpoint_api_key and the gateway sends it as the Bearer token on every request; it is stored encrypted and never echoed back. Rotate or clear it with PUT /api/models/<slug>/providers/<id>/endpoint-credential.

curl -X POST "https://api-pr-74.preview.experientiallabs.ai/api/models" \
  -H "Authorization: Bearer $EXPLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-local-model",
    "display_name": "My Local Model",
    "supported_params": {"temperature": true, "tools": true},
    "providers": [{
      "provider": "local",
      "provider_model_id": "my-model",
      "base_url": "https://your-host:8000/v1",
      "endpoint_api_key": "the-key-your-server-requires"
    }]
  }'

To add another way to reach an existing model (a local variant, a second provider), post a deployment to POST /api/models/<slug>/providers, then add it to the waterfall.

Serve it yourself

Route an existing model through an endpoint you control (a reseller or proxy) while keeping the model's own wire dialect and response shape. Unlike a local model (which creates a new, private model), this adds a per-organization lane on the existing model: a call to claude-sonnet-5still speaks the Anthropic Messages API and returns Anthropic-shaped responses, just served from your host. It is a Pro feature, and the endpoint speaks the model's own dialect (Anthropic for Claude, OpenAI-chat for GPT-family, etc.).

On the model page, open Add a way → Serve it yourself, enter the endpoint URL and its API key (optionally a served model id if your host names the model differently), and press Test connection. We send one small request in the model's dialect and only let you add the lane once it answers correctly. A failed check shows what came back and blocks the add, so a broken endpoint never lands. Once added, it appears in the waterfall like any other route; order it or turn it off there. Your key bills your host directly (the gateway adds no markup) and is stored encrypted, never echoed back.

See also

Models covers the catalog, provider waterfalls, and the two payment lanes; Errors covers what an unsupported field or a failed route returns.