Providers

Connected model billing providers.

See the OpenAPI document 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
POST	/v1/api/providers	Save a workspace model provider
DELETE	/v1/api/providers/{provider}	Disconnect a model provider
GET	/v1/api/providers/{provider}	Read a model provider configuration
PATCH	/v1/api/providers/{provider}	Update a model provider
GET	/v1/api/providers/{provider}/models	Read cached models advertised by this billing provider
POST	/v1/api/providers/{provider}/models/refresh	Refresh the connected provider model catalog
POST	/v1/api/providers/{provider}/test	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

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.