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. Free on any plan.
• 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. Connecting a key is free on any plan.

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. Connecting or rotating a key is a single upsert; verify it with a check call. Keys are write-only — reads never return secret material, only the last four characters.

curl -X PUT "https://api-pr-1588.preview.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections/openai" \
  -H "Authorization: Bearer $EXPLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret": "sk-...", "config": {}}'

# Verify it
curl -X POST "https://api-pr-1588.preview.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections/openai/check" \
  -H "Authorization: Bearer $EXPLABS_API_KEY"

Each provider is connected differently:

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-1588.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.