# Agents

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/agents` | [List the workspace's agents](#list-the-workspaces-agents) |
| `POST` | `/v1/api/agents` | [Create an agent](#create-an-agent) |
| `GET` | `/v1/api/agents/{id}` | [Get one agent](#get-one-agent) |
| `PATCH` | `/v1/api/agents/{id}` | [Update an agent](#update-an-agent) |
| `POST` | `/v1/api/agents/{id}/deactivate` | [Deactivate an agent](#deactivate-an-agent) |
| `POST` | `/v1/api/agents/{id}/fork` | [Fork an agent into a new custom one](#fork-an-agent-into-a-new-custom-one) |

## List the workspace's agents

`GET /v1/api/agents` · operation ID `listAgents`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | query | no | string | Only this project's agents plus the workspace-wide ones. Omitted, the read is every ACTIVE agent in the workspace — a deactivated one is absent from that list and still readable by id. |
| `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` | Agent[] | The matching agents. |
| `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. |

## Create an agent

`POST /v1/api/agents` · operation ID `createAgent`

**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`, `CreateAgent` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `avatarKey` | `nucleus` | `strand` | `codon` | `pheno` | `proof` | `telo` | `script` | `bot` | `spark` | `orbit` | `sprout` | `echo` | `pixel` | null | no |  |
| `avatarUrl` | string | null | no |  |
| `description` | string | null | no |  |
| `duty` | `executor` | `intake` | no |  |
| `instructions` | string | null | no |  |
| `modelOverride` | string | null | no |  |
| `name` | string | **yes** | min length 1, max length 120 |
| `pipeline` | `default` | `full` | `docs` | `security` | `lint` | no |  |
| `projectId` | string,null | no |  |
| `runtimeKind` | `claude-code` | `codex` | `cursor-agent` | `opencode` | `goose` | `qwen-code` | `pi` | `hlix` | **yes** |  |
| `runtimeVersion` | string | null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | Agent | The stored agent. `createdByUserId` and `isBuiltIn` are SERVER-SET: a caller that could set them would be able to dress a custom agent up as a vetted default. |
| `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 | Authoring a WORKSPACE-WIDE agent is owner/admin only; a project-scoped one needs `manage` on that project, which refuses every client collaborator. |
| `404` | ApiError | No such agent in this workspace — or no such project to scope it to. |
| `409` | ApiError | Another agent in this scope already holds that name, or the scope already has an intake agent — there is exactly one per scope. |
| `500` | ApiError | The agent could not be written. |

## Get one agent

`GET /v1/api/agents/{id}` · operation ID `getAgent`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | 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` | Agent | The agent. |
| `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 agent in this workspace — or no such project to scope it to. |

## Update an agent

`PATCH /v1/api/agents/{id}` · operation ID `updateAgent`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | 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`, `UpdateAgent` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `avatarKey` | `nucleus` | `strand` | `codon` | `pheno` | `proof` | `telo` | `script` | `bot` | `spark` | `orbit` | `sprout` | `echo` | `pixel` | null | no |  |
| `avatarUrl` | string | null | no |  |
| `description` | string | null | no |  |
| `duty` | `executor` | `intake` | no |  |
| `instructions` | string | null | no |  |
| `modelOverride` | string | null | no |  |
| `name` | string | no | min length 1, max length 32 |
| `pipeline` | `default` | `full` | `docs` | `security` | `lint` | no |  |
| `projectId` | string,null | no |  |
| `runtimeKind` | `claude-code` | `codex` | `cursor-agent` | `opencode` | `goose` | `qwen-code` | `pi` | `hlix` | no |  |
| `runtimeVersion` | string | null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Agent | The updated agent. |
| `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 | Authoring a WORKSPACE-WIDE agent is owner/admin only; a project-scoped one needs `manage` on that project, which refuses every client collaborator. |
| `404` | ApiError | No such agent in this workspace — or no such project to scope it to. |
| `409` | ApiError | This is a BUILT-IN and its definition is immutable — fork it and edit the fork. Or another agent in the scope holds that name, or the scope already has an intake agent. |

## Deactivate an agent

`POST /v1/api/agents/{id}/deactivate` · operation ID `deactivateAgent`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | 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` | Agent | The agent, now inactive. Allowed on a BUILT-IN on purpose: declining a default is a choice about whether to use it, not an edit to what it is. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authoring a WORKSPACE-WIDE agent is owner/admin only; a project-scoped one needs `manage` on that project, which refuses every client collaborator. |
| `404` | ApiError | No such agent in this workspace — or no such project to scope it to. |

## Fork an agent into a new custom one

`POST /v1/api/agents/{id}/fork` · operation ID `forkAgent`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | 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`, `ForkAgent` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `instructions` | string | null | no |  |
| `name` | string | **yes** | min length 1, max length 120 |
| `projectId` | string,null | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | Agent | The fork. `duty` is CARRIED (a fork of the intake agent is how a project gets its own), while `mastraRole`, `isBuiltIn` and authorship are NOT — a fork is never a built-in, whatever it came from. |
| `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 | Authoring a WORKSPACE-WIDE agent is owner/admin only; a project-scoped one needs `manage` on that project, which refuses every client collaborator. |
| `404` | ApiError | No such agent in this workspace — or no such project to scope it to. |
| `409` | ApiError | Another agent in this scope already holds that name, or the scope already has an intake agent — there is exactly one per scope. |
| `500` | ApiError | The fork could not be written. |

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