Tasks

A task is the atomic unit of execution — one worker agent, one git worktree, one branch, one outcome. These operations create and read tasks, their comments, their verified review evidence, and their status stream.

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/tasks	List tasks in the workspace
POST	/v1/api/tasks	Create a standalone task
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
POST	/v1/api/tasks/{id}/execute	Execute a task standalone (not implemented)
GET	/v1/api/tasks/{id}/review	Get the verified review evidence for a task
GET	/v1/api/tasks/{id}/stream	Stream a task’s status changes (SSE)

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.

Create a standalone task

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
projectId	string (uuid)	yes
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).
500	ApiError	The task could not be created.

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.

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

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
status	queued	blocked	building
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

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.

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

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.

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.

Execute a task standalone (not implemented)

POST /v1/api/tasks/{id}/execute · operation ID executeTask

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
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.
501	ApiError	There is no standalone single-task run. Execute the task’s cycle instead. The task is left untouched.

Get the verified review evidence for a task

GET /v1/api/tasks/{id}/review · operation ID getTaskReviewEvidence

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	TaskReviewEvidence	The same observation the QA evaluator reviews. Repo-backed, it is a three-dot compare of the task branch against the commit it was cut from; repo-less, it is the delivered workspace archive and there is no diff.
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, or the task has no evidence to show (no branch, no recorded branch point).
502	ApiError	The repository host could not be reached.

Stream a task’s status changes (SSE)

GET /v1/api/tasks/{id}/stream · operation ID streamTask

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	string	One frame per status change, a keepalive event roughly every 30s, and the stream closes on a terminal status or after ~20 minutes. A task that does not exist is reported as a {"error":"Task not found"} FRAME on an open 200 stream, not as a 404.
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 task’s project is out of reach — a client collaborator it was never shared with (existence is deliberately not revealed).

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.