Model providers

Providers are bring-your-own: org-scoped rows (credentials plus model list) merged over the built-in platform and environment providers into one catalog that agents pick from. Adding one needs the byok plan feature (Pro and Enterprise).

RowsCopy Anchor Link

Each provider has a name (unique in the org — a duplicate is a 409), an SDK (openai, anthropic, google, gateway, or openai-compatible), a write-only API key, an enabled flag, and 1–200 models. Each model needs a value (no whitespace, unique in the row) and may add label, description, author, contextWindow, maxOutput, and reasoningEfforts (the effort levels a reasoning model accepts).

Two constraints with teeth:

• baseUrl is required for openai-compatible and refused for every other SDK. First-party endpoints are fixed — otherwise vendor-executed tools would leak to tenant hosts. Switching a row to a first-party SDK drops a stored base URL.
• The key is tri-state on update: omitted keeps, null clears, string replaces.

Responses never return the key — only a presence flag and last four — plus builtin, usability (with a reason when unusable), and which platform models the row overrides.

Routing and the catalogCopy Anchor Link

Your rows route first, then the platform's, so a row listing a platform model value takes that model over for the org (bring your own key) and can add models of its own. Disabled rows drop out of routing and the catalog entirely. The catalog is also cut to what the plan runs: Free keeps only its own two models, and paid plans never see them.

Settings → Model ProvidersCopy Anchor Link

The page tables your rows and the built-ins; it needs modelProvider:read, so non-admins get a forbidden page. Built-ins are read-only — editing or testing one is refused; add a row listing the same models to override it.

Test on an openai-compatible row asks the endpoint for its model list and reports success, the upstream HTTP status, and how many models it advertised. On a first-party SDK it only reports whether a key is stored — those are verified on first use.

PermissionsCopy Anchor Link

The merged catalog (GET /model-providers/catalog) needs only agent:read, so members and even embed visitors can see what an agent offers; it never carries base URLs or key state. Provider CRUD needs modelProvider:*, which owners and admins hold.