# Providers

Connected model billing providers.

See the [OpenAPI document](/openapi.json) for schemas and operation IDs.

## Prerequisites

- Protected operations require an API key in `x-api-key` or a browser session cookie; some actions require a verified user session
- Tenant-scoped operations use `X-Organization-Id`; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/providers` | [List connected model billing providers](#list-connected-model-billing-providers) |
| `POST` | `/v1/api/providers` | [Save a workspace model provider](#save-a-workspace-model-provider) |
| `DELETE` | `/v1/api/providers/{provider}` | [Disconnect a model provider](#disconnect-a-model-provider) |
| `GET` | `/v1/api/providers/{provider}` | [Read a model provider configuration](#read-a-model-provider-configuration) |
| `PATCH` | `/v1/api/providers/{provider}` | [Update a model provider](#update-a-model-provider) |
| `GET` | `/v1/api/providers/{provider}/models` | [Read cached models advertised by this billing provider](#read-cached-models-advertised-by-this-billing-provider) |
| `POST` | `/v1/api/providers/{provider}/models/refresh` | [Refresh the connected provider model catalog](#refresh-the-connected-provider-model-catalog) |
| `POST` | `/v1/api/providers/{provider}/test` | [Test provider credentials without inference](#test-provider-credentials-without-inference) |

## List connected model billing providers

`GET /v1/api/providers` · operation ID `listModelProviders`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ModelProviderConfig[] | Safe workspace provider configuration, no credentials or model payloads. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Save a workspace model provider

`POST /v1/api/providers` · operation ID `connectModelProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `UpsertProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string \| null | no |  |
| `baseUrl` | string (uri) \| null | no |  |
| `enabled` | boolean | no |  |
| `metadata` | object \| null | no |  |
| `provider` | `openai` \| `anthropic` \| `openrouter` \| `moonshot` \| `deepseek` \| `zai` \| `google` \| `xai` \| `mistral` \| `groq` | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | ModelProviderConfig | Provider configuration saved. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Disconnect a model provider

`DELETE /v1/api/providers/{provider}` · operation ID `deleteModelProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ModelProviderRemoved | Disconnected. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read a model provider configuration

`GET /v1/api/providers/{provider}` · operation ID `getModelProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ModelProviderConfig | Safe provider configuration. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | No stored provider credentials. |

## Update a model provider

`PATCH /v1/api/providers/{provider}` · operation ID `updateModelProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `PatchProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string \| null | no |  |
| `baseUrl` | string (uri) \| null | no |  |
| `enabled` | boolean | no |  |
| `metadata` | object \| null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ModelProviderConfig | Provider configuration saved. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read cached models advertised by this billing provider

`GET /v1/api/providers/{provider}/models` · operation ID `getModelProviderModels`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | CoderAccountModelCatalog | Cached advertised metadata; never probes or proves entitlement. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Refresh the connected provider model catalog

`POST /v1/api/providers/{provider}/models/refresh` · operation ID `refreshModelProviderModels`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | CoderAccountModelCatalog | Bounded advertised metadata. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | Connect this provider or refresh after its credential changed. |
| `502` | ApiError | Provider model list unavailable. |

## Test provider credentials without inference

`POST /v1/api/providers/{provider}/test` · operation ID `testModelProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `TestModelProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | no | min length 1 |
| `baseUrl` | string (uri) \| null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ModelProviderProbe | Read-only provider check. |
| `400` | ValidationError \| ApiError | Invalid provider or body. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency only; mutations require owner/admin. |
| `404` | ApiError | No stored provider credentials. |
| `502` | ModelProviderProbe | Provider check failed. |

## If a request fails

The response table for each operation lists its documented errors. Common status codes include:

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — check the resource ID and your access to the selected Workspace.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)