Model configuration

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json serves.

Prerequisites

• An API key in x-api-key, or a browser session cookie
• X-Organization-Id naming the workspace to act in, unless the session already has an active one
• The base URL for your deployment, https://server.hlix.ai by default

Operations

Method	Path	Operation
GET	/v1/api/model-config	List the workspace’s per-role model overrides
DELETE	/v1/api/model-config/{role}	Clear one role’s model override
GET	/v1/api/model-config/{role}	Get one role’s model override
PUT	/v1/api/model-config/{role}	Set one role’s model override
GET	/v1/api/model-config/catalog	List current tool-capable chat models
DELETE	/v1/api/model-config/harness	Clear the workspace-wide harness
GET	/v1/api/model-config/harness	List the workspace’s harness preferences
PUT	/v1/api/model-config/harness	Set the workspace-wide harness
DELETE	/v1/api/model-config/harness/{projectId}	Clear a project’s harness
PUT	/v1/api/model-config/harness/{projectId}	Set a project’s harness
GET	/v1/api/model-config/harness/{projectId}/resolved	Resolve a project’s harness, with provenance
GET	/v1/api/model-config/harness/resolved	Resolve the workspace’s harness, with provenance

List the workspace’s per-role model overrides

GET /v1/api/model-config · operation ID listModelPreferences

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	ModelPreference[]	Only the roles that actually override something. An absent role is on the platform default, not on a zero.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Clear one role’s model override

DELETE /v1/api/model-config/{role} · operation ID clearModelPreference

Parameters

Name	In	Required	Type	Description
role	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	DeletedAck	Cleared; the role falls back to the platform default. Clearing a role that had no override answers the same 200.
400	ApiError	The path segment is not an agent role, or the request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Get one role’s model override

GET /v1/api/model-config/{role} · operation ID getModelPreference

Parameters

Name	In	Required	Type	Description
role	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	ModelPreference	The override.
400	ApiError	The path segment is not an agent role, or the request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	This role has no override; the platform default applies.

Set one role’s model override

PUT /v1/api/model-config/{role} · operation ID setModelPreference

Parameters

Name	In	Required	Type	Description
role	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, UpsertModelPreference (required)

Property	Type	Required	Notes
maxTokens	integer	null	no
modelIdentifier	string	yes	min length 1, max length 200
temperature	number	null	no

Responses

Status	Body	Description
200	ModelPreference	The stored override.
400	ValidationError | ApiError	The path segment is not an agent role — or the JSON body failed validation, or the request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

List current tool-capable chat models

GET /v1/api/model-config/catalog · operation ID listModelCatalog

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	ModelCatalog	Cached OpenRouter catalog, with freshness metadata.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Clear the workspace-wide harness

DELETE /v1/api/model-config/harness · operation ID clearOrganizationHarness

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	DeletedAck	Cleared; every project now falls back to the default.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Changing the WORKSPACE-wide harness is owner/admin only — it names the coder for every project at once.
404	ApiError	There was no workspace-wide preference to clear.

List the workspace’s harness preferences

GET /v1/api/model-config/harness · operation ID listHarnessPreferences

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	HarnessPreference[]	The organization-wide row first (its projectId is null), then one row per project that overrides it.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Set the workspace-wide harness

PUT /v1/api/model-config/harness · operation ID setOrganizationHarness

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, UpsertHarnessPreference (required)

Property	Type	Required	Notes
harness	claude-code	codex	cursor-agent

Responses

Status	Body	Description
200	HarnessPreference	The stored preference.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Changing the WORKSPACE-wide harness is owner/admin only — it names the coder for every project at once.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Clear a project’s harness

DELETE /v1/api/model-config/harness/{projectId} · operation ID clearProjectHarness

Parameters

Name	In	Required	Type	Description
projectId	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	DeletedAck	Cleared; the project now inherits the workspace’s preference, or the default.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Choosing a project’s coder is agency administration; a client collaborator is refused even with steer access.
404	ApiError	No such project in this workspace, or it had no preference to clear.

Set a project’s harness

PUT /v1/api/model-config/harness/{projectId} · operation ID setProjectHarness

Parameters

Name	In	Required	Type	Description
projectId	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, UpsertHarnessPreference (required)

Property	Type	Required	Notes
harness	claude-code	codex	cursor-agent

Responses

Status	Body	Description
200	HarnessPreference	The stored preference.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Choosing a project’s coder is agency administration; a client collaborator is refused even with steer access.
404	ApiError	No such project in this workspace.

Resolve a project’s harness, with provenance

GET /v1/api/model-config/harness/{projectId}/resolved · operation ID getResolvedProjectHarness

Parameters

Name	In	Required	Type	Description
projectId	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	ResolvedHarness	What would run for this project, and which setting chose it.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	No such project in this workspace.

Resolve the workspace’s harness, with provenance

GET /v1/api/model-config/harness/resolved · operation ID getResolvedOrganizationHarness

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	ResolvedHarness	What would run at workspace scope, and which setting chose it.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

If a request fails

These apply to every operation on this page.

• 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 — no such resource in this workspace. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
• 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 referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.