Models

The catalog

Every model is a slug (for example claude-opus-5, gpt-5.5, gemini-3.7-flash) with a display name, context window, input and output modalities, and pricing. The catalog is the public rows plus your organization's own custom and local models. Browse it in the web app at /models, or read it over the API: GET /api/modelsis public and needs no key (it returns the public rows), and sending your key adds your organization's own custom and local models.

curl "https://api-pr-668.preview.experientiallabs.ai/api/models?sort=preferred&limit=20"

Filter and sort with query parameters: modality, category, provider, min_context, max_input_micro_usd_per_million, supports, and sort (one of preferred, price, age, context, throughput) with limit and offset. One model's detail is GET /api/models/<slug>; its deployments are GET /api/models/<slug>/providers.

Provider waterfalls

A slug does not point at one provider; it points at a waterfall, an ordered list of deployments (each a provider plus a provider model id, and for some providers a base_url, region, or api_version). The gateway tries each rung in order, fails over on capacity and transport errors, and returns the first success. The routing is invisible to the caller: you get one OpenAI-shaped response.

Every model has a default chain. An organization can override it with its own ordering. Read and replace the chain with the waterfall endpoints; model_provider_ids is the ordered list of deployment ids, and an empty list clears your override (falling back to the default).

# Read the chain for a model
curl "https://api-pr-668.preview.experientiallabs.ai/api/models/claude-opus-5/waterfall" \
  -H "Authorization: Bearer $EXPLABS_API_KEY"

# Replace your org's override with an ordered deployment list
curl -X PUT "https://api-pr-668.preview.experientiallabs.ai/api/models/claude-opus-5/waterfall" \
  -H "Authorization: Bearer $EXPLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_provider_ids": ["<deployment-a>", "<deployment-b>"]}'

Two lanes: BYOK and platform-funded

Each deployment is paid for through one of two lanes, and the gateway adds no markup on either:

• Pass-through (BYOK): your own provider key. The provider bills you directly. These deployments are customer_managed.
• Platform-funded: our credits, priced from the public catalog. These deployments are host_managed and are seeded by operations, never self-asserted.

To use the pass-through lane, connect a provider key. Connecting or rotating a key is a single upsert; verify it with a check call. Keys are write-only: reads never return secret material.

curl -X PUT "https://api-pr-668.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-668.preview.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections/openai/check" \
  -H "Authorization: Bearer $EXPLABS_API_KEY"

Each provider is connected differently:

Custom and local models

Add your own model as an ordinary catalog row scoped to your org: one model plus at least one deployment. A local deployment points at any OpenAI-compatible server through its base_url, so a model you host yourself is callable by slug just like a hosted one.

curl -X POST "https://api-pr-668.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",
    "providers": [{
      "provider": "local",
      "provider_model_id": "my-model",
      "base_url": "https://your-host:8000/v1"
    }]
  }'

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.

See also

The API reference lists every field and response shape, and Errors covers what a failed route returns.