Authentication
Send the session JWT fromPOST /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
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 containsoutput.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
Thelabel 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_nametwice 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_urlorapi_key. - The next sync checks
default_modelagainst the live model list. If it’s missing, the sync records a warning inlast_sync_errorbut 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
200withdiscovered_models: 0, and the provider’slast_sync_statusbecomesfailed(orunsupportedwhen the endpoint lists no usable models). Check it with List custom providers. - When the listing is empty, the existing catalog entries are kept.