Agents

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/agents	List the workspace’s agents
POST	/v1/api/agents	Create an agent
GET	/v1/api/agents/{id}	Get one agent
PATCH	/v1/api/agents/{id}	Update an agent
POST	/v1/api/agents/{id}/deactivate	Deactivate an agent
POST	/v1/api/agents/{id}/fork	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
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
projectId	string,null	no
runtimeKind	claude-code	codex	cursor-agent
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
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
projectId	string,null	no
runtimeKind	claude-code	codex	cursor-agent
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 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.