> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom providers API

> Register, test, update, sync and remove your own OpenAI-compatible, Azure OpenAI and Bedrock Converse endpoints.

A custom provider is a model endpoint you register yourself so the [LLM router](https://docs.nasiko.com/models/llm-router.md) can route to it. Once registered, its models appear beside the built-in providers and can be used in LLM configs. Behavioral guide: [Providers](https://docs.nasiko.com/models/providers.md).

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`](https://docs.nasiko.com/api-reference/account) as `Authorization: Bearer <token>`, or use the dashboard cookie.

| Route | Who can call it |
| - | - |
| `GET /api/custom-providers` | Any authenticated user |
| Every other route on this page | Superuser only |

The bootstrap admin account created on first start is a superuser. Superuser is a separate flag from role — see [Role vs. superuser](https://docs.nasiko.com/governance/access-control/users-and-teams.md).

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

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/custom-providers` | List registered custom providers |
| `POST` | `/api/custom-providers/test` | Probe an endpoint before you register it |
| `POST` | `/api/custom-providers` | Register a provider |
| `PATCH` | `/api/custom-providers/{id}` | Update a provider |
| `DELETE` | `/api/custom-providers/{id}` | Remove a provider |
| `POST` | `/api/custom-providers/{id}/sync` | Refresh a provider's model list now |

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

| `kind` | Use for | Notes |
| - | - | - |
| `openai` (default) | Any OpenAI-compatible endpoint: LiteLLM, vLLM, Ollama, OpenRouter, and similar | Models are listed from the endpoint's `/models` route |
| `azure-openai` | Azure OpenAI deployments | `api_version` is required (for example `2024-10-21`). A trailing `/openai` on `base_url` is removed |
| `bedrock-converse` | Amazon Bedrock through the Converse API | Only active models that support Converse are listed |

`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

```bash theme={null}
curl https://<your-host>/api/custom-providers \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10",
      "label": "team-litellm",
      "display_name": "Team LiteLLM",
      "base_url": "https://litellm.internal.example.com/v1",
      "kind": "openai",
      "api_version": null,
      "default_model": "gpt-4o-mini",
      "catalog_sync_enabled": true,
      "api_key_set": true,
      "last_sync_at": "2026-11-14T08:00:12.418Z",
      "last_sync_status": "ok",
      "last_sync_error": null,
      "created_at": "2026-10-02T15:21:40.002Z"
    }
  ],
  "status_code": 200,
  "message": "Custom providers retrieved"
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Provider ID. Use it in the `{id}` routes |
| `label` | string | The provider name the router and LLM configs use. Generated from `display_name` when you register; it doesn't change when you rename the provider |
| `display_name` | string | Name shown in the dashboard |
| `base_url` | string | Normalized endpoint URL |
| `kind` | string | `openai`, `azure-openai`, or `bedrock-converse` |
| `api_version` | string or null | Azure API version. `null` for other kinds |
| `default_model` | string or null | Model used when a request doesn't name one the provider serves |
| `catalog_sync_enabled` | boolean | Whether the scheduled model-catalog sync refreshes this provider |
| `api_key_set` | boolean | `true` when an API key is stored. The key itself is never returned |
| `last_sync_at` | timestamp or null | When the model list was last refreshed. `null` until the first sync |
| `last_sync_status` | string or null | `ok`, `failed` (the model listing couldn't be fetched), or `unsupported` (the endpoint returned no usable models — enter model names manually) |
| `last_sync_error` | string or null | Why the last sync failed. When the status is `ok`, this can still hold a warning that `default_model` is no longer in the provider's live model list |
| `created_at` | timestamp | When the provider was registered |

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | Missing, expired, or invalid session |
| `500` | `internal error` (plain text) | Server-side failure |

***

## 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

| Field | Type | Required | Description |
| - | - | - | - |
| `base_url` | string | Yes | Endpoint URL |
| `api_key` | string | Yes | API key for the endpoint. Not stored |
| `kind` | string | No | `openai` (default), `azure-openai`, or `bedrock-converse` |
| `api_version` | string | For `azure-openai` | Azure API version, for example `2024-10-21` |
| `model` | string | No | When set, sends one short chat request to this model (a deployment name under Azure, a model ID under Bedrock) to prove a real call works |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/custom-providers/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "https://litellm.internal.example.com/v1",
    "api_key": "sk-...",
    "kind": "openai",
    "model": "gpt-4o-mini"
  }'
```

```json theme={null}
{
  "data": {
    "chat_ok": true,
    "models": ["gpt-4o", "gpt-4o-mini", "text-embedding-3-small"]
  },
  "status_code": 200,
  "message": "Endpoint test complete"
}
```

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

```json theme={null}
{
  "data": {
    "chat_ok": false,
    "chat_error": "chat test returned 401 Unauthorized: {\"error\":\"invalid api key\"}",
    "models": []
  },
  "status_code": 200,
  "message": "Chat test failed"
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `chat_ok` | boolean | `true` when the chat probe got a valid reply. `false` when it failed **or** when you didn't send `model` (nothing was tested) |
| `chat_error` | string | Present only when the chat probe failed. Includes the upstream status and the first 200 characters of its reply |
| `models` | string\[] | Model IDs the endpoint lists. Empty when the listing call fails or returns nothing |

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `base_url and api_key are required` | Either is empty |
| `400` | `api_version is required for kind 'azure-openai' (e.g. 2024-10-21)` | Azure kind without a version |
| `400` | `unknown kind '<kind>' (expected 'openai', 'azure-openai', or 'bedrock-converse')` | Unsupported `kind` |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `403` | `requires superuser` | Caller isn't a superuser |

### 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

| Field | Type | Required | Description |
| - | - | - | - |
| `display_name` | string | Yes | Name shown in the dashboard. Also the source of the provider's `label` |
| `base_url` | string | Yes | Endpoint URL |
| `api_key` | string | Yes | API key. Stored encrypted and never returned |
| `kind` | string | No | `openai` (default), `azure-openai`, or `bedrock-converse` |
| `api_version` | string | For `azure-openai` | Azure API version. Ignored for other kinds |
| `catalog_sync_enabled` | boolean | No | Default `true`. When `false`, the scheduled sync skips this provider; you can still sync it on demand |

To set a default model, register first and then send `default_model` with [Update a provider](#update-a-provider). The dashboard does this in one step for you.

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/custom-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Team LiteLLM",
    "base_url": "https://litellm.internal.example.com/v1",
    "api_key": "sk-...",
    "kind": "openai"
  }'
```

```json theme={null}
{
  "data": {
    "id": "0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10",
    "label": "team-litellm",
    "discovered_models": 3,
    "priced_models": 2
  },
  "status_code": 201,
  "message": "Custom provider registered"
}
```

| Field | Type | Description |
| - | - | - |
| `id` | UUID | New provider ID |
| `label` | string | Generated provider name |
| `discovered_models` | integer | Models found by the initial sync. `0` if the listing failed — the provider is still registered, and `last_sync_status` explains why |
| `priced_models` | integer | Models that received [price book](https://docs.nasiko.com/tokenops/pricing.md) rows. Until a model has a price, TokenOps marks its cost as estimated |

### 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

| Status | Body | When |
| - | - | - |
| `400` | `display_name and base_url are required` | Either is empty |
| `400` | `api_key is required` | `api_key` is empty |
| `400` | `api_version is required for kind 'azure-openai' (e.g. 2024-10-21)` | Azure kind without a version |
| `400` | `unknown kind '<kind>' (...)` | Unsupported `kind` |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `403` | `requires superuser` | Caller isn't a superuser |
| `409` | `could not generate a unique label for '<display_name>'` | Ten labels derived from this name are already taken. Choose a different display name |
| `500` | `internal error` | Server-side failure |

### 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Provider ID |

### Request body

All fields are optional.

| Field | Type | Description |
| - | - | - |
| `display_name` | string | New display name. Doesn't change `label` |
| `base_url` | string | New endpoint URL. Normalized for the provider's kind |
| `api_key` | string | Replaces the stored key |
| `api_version` | string | New Azure API version. For an `azure-openai` provider, an empty value is rejected |
| `default_model` | string | Model to fall back to when a request names none the provider serves |
| `catalog_sync_enabled` | boolean | Turn the scheduled model sync on or off |

`kind` can't be changed. To switch kinds, register a new provider.

### Example

```bash theme={null}
curl -X PATCH https://<your-host>/api/custom-providers/0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "default_model": "gpt-4o-mini" }'
```

```json theme={null}
{
  "data": { "id": "0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10" },
  "status_code": 200,
  "message": "Custom provider updated"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `api_version cannot be cleared for kind 'azure-openai'` | Empty `api_version` on an Azure provider |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `403` | `requires superuser` | Caller isn't a superuser |
| `404` | `no such custom provider` | Unknown or deleted `id` |
| `500` | `internal error` | Server-side failure |

### Notes

* Updating doesn't trigger a model sync. Call [Sync models now](#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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Provider ID |

### Example

```bash theme={null}
curl -X DELETE https://<your-host>/api/custom-providers/0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10 \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": { "id": "0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10" },
  "status_code": 200,
  "message": "Custom provider deleted"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `403` | `requires superuser` | Caller isn't a superuser |
| `404` | `no such custom provider` | Unknown or already deleted `id` |
| `409` | JSON, see below | One or more LLM configs still use this provider |
| `500` | `internal error` | Server-side failure |

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

```json theme={null}
{
  "message": "provider is still referenced by LLM configs; repoint them first",
  "referencing_configs": ["support-default", "batch-cheap"]
}
```

### 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Provider ID |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/custom-providers/0b9a3c1e-6f2d-4e8a-9b51-2c7d4e6f8a10/sync \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": { "discovered_models": 4 },
  "status_code": 200,
  "message": "Sync complete"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | No valid session |
| `403` | `requires superuser` | Caller isn't a superuser |
| `404` | `no such custom provider` | Unknown or deleted `id` |
| `500` | `internal error` | Server-side failure |

### 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](#list-custom-providers).
* When the listing is empty, the existing catalog entries are kept.

## Related

* [Providers](https://docs.nasiko.com/models/providers.md)
* [LLM router](https://docs.nasiko.com/models/llm-router.md)
* [Pricing](https://docs.nasiko.com/tokenops/pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.