# Model configuration

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) 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](#list-the-workspaces-per-role-model-overrides) |
| `DELETE` | `/v1/api/model-config/{role}` | [Clear one role's model override](#clear-one-roles-model-override) |
| `GET` | `/v1/api/model-config/{role}` | [Get one role's model override](#get-one-roles-model-override) |
| `PUT` | `/v1/api/model-config/{role}` | [Set one role's model override](#set-one-roles-model-override) |
| `GET` | `/v1/api/model-config/catalog` | [List current tool-capable chat models](#list-current-tool-capable-chat-models) |
| `DELETE` | `/v1/api/model-config/harness` | [Clear the workspace-wide harness](#clear-the-workspace-wide-harness) |
| `GET` | `/v1/api/model-config/harness` | [List the workspace's harness preferences](#list-the-workspaces-harness-preferences) |
| `PUT` | `/v1/api/model-config/harness` | [Set the workspace-wide harness](#set-the-workspace-wide-harness) |
| `DELETE` | `/v1/api/model-config/harness/{projectId}` | [Clear a project's harness](#clear-a-projects-harness) |
| `PUT` | `/v1/api/model-config/harness/{projectId}` | [Set a project's harness](#set-a-projects-harness) |
| `GET` | `/v1/api/model-config/harness/{projectId}/resolved` | [Resolve a project's harness, with provenance](#resolve-a-projects-harness-with-provenance) |
| `GET` | `/v1/api/model-config/harness/resolved` | [Resolve the workspace's harness, with provenance](#resolve-the-workspaces-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` | `opencode` | `goose` | `qwen-code` | `pi` | `hlix` | **yes** |  |

**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` | `opencode` | `goose` | `qwen-code` | `pi` | `hlix` | **yes** |  |

**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 reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)