Skip to main content
A custom provider is a model endpoint you register yourself so the LLM router can route to it. Once registered, its models appear beside the built-in providers and can be used in LLM configs. Behavioral guide: Providers. The dashboard calls these routes from the LLM router screen (Register any OpenAI-compatible endpoint, the provider’s edit form, Sync now, and delete).

Authentication

Send the session JWT from POST /api/auth/login as Authorization: Bearer <token>, or use the dashboard cookie. The bootstrap admin account created on first start is a superuser. Superuser is a separate flag from role — see Role vs. superuser. Requests without a valid session get 401 with { "data": null, "status_code": 401, "message": "..." }. A signed-in caller who isn’t a superuser gets 403 with the plain-text body requires superuser.

Endpoints

Successful responses use the envelope { "data": ..., "status_code": <n>, "message": "..." }. Most error responses on these routes are plain text, not JSON — read the body as a string. The one exception is the 409 from delete, described below.

Provider kinds

base_url is trimmed and any trailing / is removed before it is stored.

List custom providers

GET /api/custom-providers Returns every registered custom provider, sorted by display name. Use it to show which endpoints exist, whether each has a key on file, and how its last model sync went. Auth: session JWT or dashboard cookie. Role: any authenticated user.

Example

Response fields

Errors


Test an endpoint

POST /api/custom-providers/test Probes an endpoint with the credentials you supply, without saving anything. Use it before registering to confirm the URL and key work and to see which models the endpoint lists. The dashboard calls it from the registration form. Auth: session JWT or dashboard cookie. Role: superuser.

Request body

Example

When the chat probe fails, the response is still 200, with the reason and no model list:

Response fields

Errors

Notes

  • Each probe call times out after 20 seconds.
  • A chat probe passes when an OpenAI-style reply contains choices, or a Bedrock reply contains output.message.

Register a provider

POST /api/custom-providers Registers an endpoint and immediately syncs its model list and prices. Returns 201. Auth: session JWT or dashboard cookie. Role: superuser.

Request body

To set a default model, register first and then send default_model with Update a provider. The dashboard does this in one step for you.

Example

How the label is generated

The label is display_name lowercased, with every run of non-alphanumeric characters turned into a single -, trimmed, and cut to 40 characters. If the result would be openai, anthropic, or gemini, -custom is appended. If the label is already taken, -1 through -9 is appended. A name too short to produce a label gets custom- plus a random suffix.

Errors

Notes

  • Not idempotent. Registering the same display_name twice creates two providers with different labels.
  • The request waits for the initial model sync and price sync, so it can take as long as the endpoint’s model listing.

Update a provider

PATCH /api/custom-providers/{id} Changes one or more fields of a provider. Fields you leave out keep their current value. Auth: session JWT or dashboard cookie. Role: superuser.

Path parameters

Request body

All fields are optional. kind can’t be changed. To switch kinds, register a new provider.

Example

Errors

Notes

  • Updating doesn’t trigger a model sync. Call Sync models now after changing base_url or api_key.
  • The next sync checks default_model against the live model list. If it’s missing, the sync records a warning in last_sync_error but doesn’t change your choice.

Delete a provider

DELETE /api/custom-providers/{id} Removes a provider and its discovered models from the catalog. Auth: session JWT or dashboard cookie. Role: superuser.

Path parameters

Example

Errors

The 409 body is JSON and names the configs to repoint first:

Notes

  • Delete is refused while any LLM config uses the provider. Point those configs at another provider, then retry.
  • The provider’s spend history stays in TokenOps after deletion.

Sync models now

POST /api/custom-providers/{id}/sync Fetches the provider’s model list right now and replaces its catalog entries. Use it after changing the URL or key, or to pick up newly deployed models without waiting for the scheduled sync. This is the Sync now button on the LLM router screen. It works even when catalog_sync_enabled is false. Auth: session JWT or dashboard cookie. Role: superuser.

Path parameters

Example

Errors

Notes

  • An unreachable endpoint doesn’t produce an error. The call returns 200 with discovered_models: 0, and the provider’s last_sync_status becomes failed (or unsupported when the endpoint lists no usable models). Check it with List custom providers.
  • When the listing is empty, the existing catalog entries are kept.