Tasks
Tasks, comments and review evidence.
A task is one checklist item within a cycle. A build agent delivers the cycle’s tasks together on its branch. These operations create and read tasks, comments and recorded review evidence. Watch live task status through @hlix/sdk (hlix.live.task).
See the OpenAPI document for schemas and operation IDs.
Prerequisites
Section titled “Prerequisites”- Protected operations require an API key in
x-api-keyor 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.aiby default
Operations
Section titled “Operations”| Method | Path | Operation |
|---|---|---|
GET |
/v1/api/tasks |
List tasks in the workspace |
POST |
/v1/api/tasks |
Create a task; taskConfig delegates it through a one-task cycle |
GET |
/v1/api/tasks/{id} |
Get one task |
PATCH |
/v1/api/tasks/{id} |
Update a task’s title, description or status |
GET |
/v1/api/tasks/{id}/comments |
List the comments on a task |
POST |
/v1/api/tasks/{id}/comments |
Comment on a task |
List tasks in the workspace
Section titled “List tasks in the workspace”GET /v1/api/tasks · operation ID listTasks
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
projectId |
query | no | string | Only tasks in this project. |
status |
query | no | string | Only tasks in this status. |
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 |
Task[] | The matching tasks. |
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 a task; taskConfig delegates it through a one-task cycle
Section titled “Create a task; taskConfig delegates it through a one-task cycle”POST /v1/api/tasks · operation ID createTask
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, CreateTask (required)
| Property | Type | Required | Notes |
|---|---|---|---|
description |
string | yes | min length 1, max length 5000 |
doneWhen |
string | no | min length 1, max length 1000 |
projectId |
string (uuid) | yes | |
taskConfig |
object | no | |
title |
string | no | min length 1, max length 200 |
Responses
| Status | Body | Description |
|---|---|---|
201 |
Task | The created task. |
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 | 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 — or a client collaborator it was never shared with (existence is deliberately not revealed). |
409 |
ApiError | The project is archived and does not accept new tasks. |
500 |
ApiError | The task could not be created. |
Get one task
Section titled “Get one task”GET /v1/api/tasks/{id} · operation ID getTask
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. |
X-Client-Portal |
header | no | string | The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access. |
Responses
| Status | Body | Description |
|---|---|---|
200 |
Task | The task. |
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 task in this workspace. |
Update a task’s title, description or status
Section titled “Update a task’s title, description or status”PATCH /v1/api/tasks/{id} · operation ID updateTask
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, UpdateTask (required)
| Property | Type | Required | Notes |
|---|---|---|---|
description |
string | no | min length 1, max length 5000 |
doneWhen |
string | null | no | |
status |
queued | blocked | building | testing | reviewing | approved | merging | merged | pr_created | ci_passing | done | failed |
no | |
title |
string | no | min length 1, max length 200 |
Responses
| Status | Body | Description |
|---|---|---|
200 |
Task | The updated task. |
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 | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
404 |
ApiError | No such task in this workspace. |
List the comments on a task
Section titled “List the comments on a task”GET /v1/api/tasks/{id}/comments · operation ID listTaskComments
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. |
X-Client-Portal |
header | no | string | The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access. |
Responses
| Status | Body | Description |
|---|---|---|
200 |
TaskComment[] | The task’s comment thread, oldest first. |
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 task in this workspace. |
Comment on a task
Section titled “Comment on a task”POST /v1/api/tasks/{id}/comments · operation ID addTaskComment
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. |
X-Client-Portal |
header | no | string | The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access. |
Request body — application/json, AddTaskComment (required)
| Property | Type | Required | Notes |
|---|---|---|---|
body |
string | yes | min length 1, max length 10000 |
messageId |
string (uuid) | no |
Responses
| Status | Body | Description |
|---|---|---|
201 |
TaskComment | The stored comment. |
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 | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
404 |
ApiError | No such task in this workspace. |
409 |
ApiError | The supplied messageId is already in use — either on another conversation, or on this one with different content. |
If a request fails
Section titled “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. AValidationErrorbody carries the failing fields; anApiErrorbody carries onlyerror.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
Section titled “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.