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.

Experiential Cloud is a curated collection of models, hosted and optimized by Experiential Labs. Those slugs appear in the catalog like any other model. Call them with your Experiential Labs key. They are not a provider connection you attach yourself.

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

Each provider is connected differently:

Estimated vs measured stats

Every route carries the source of its numbers so you can tell a seeded estimate from something we measured on our own serving, and a field flips from estimate to measured once we have enough volume to trust it:

• Stats (uptime, throughput, latency): seeded values are stats_source = 'openrouter'. Once a route has enough completed requests in the trailing 30 days, the catalog overlays values measured from our usage ledger and marks them stats_source = 'observed'. Below that floor the seeded estimate stands.
• Pricing: real prices carry their source (openrouter, provider-docs, aws-price-list); a value we had to guess is pricing_source = 'estimate' and is display-only , an estimated price is never billed or served on the platform lane.

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. 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 (views show only its last four characters). Rotate or clear it with PUT /api/models/<slug>/providers/<id>/endpoint-credential.

curl -X POST "https://api-pr-884.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",
      "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.

See also

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