Cycles

A cycle is a multi-task unit of work with its own conversation. These operations create cycles, dispatch them, add tasks to them, and read their events, timeline, usage and artifacts.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

• Protected operations require an API key in x-api-key or 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.ai by default

Operations

Method	Path	Operation
GET	/v1/api/cycles	List cycles
DELETE	/v1/api/cycles/{id}	Delete a draft or failed cycle
GET	/v1/api/cycles/{id}	Get one cycle with its tasks
PATCH	/v1/api/cycles/{id}	Update a cycle’s title, description or target branch
GET	/v1/api/cycles/{id}/approvals	List a cycle’s approvals
GET	/v1/api/cycles/{id}/artifacts	List a cycle’s stored artifacts
GET	/v1/api/cycles/{id}/artifacts/{filename}	Get a signed download URL for one cycle artifact
PATCH	/v1/api/cycles/{id}/assign	Hand a cycle to a teammate
POST	/v1/api/cycles/{id}/continue	Admit a branch cycle once its branch is at the pushed commit
GET	/v1/api/cycles/{id}/e2e	The cycle’s user-side verification: journeys, outcomes and evidence keys
GET	/v1/api/cycles/{id}/events	List a cycle’s own events
POST	/v1/api/cycles/{id}/execute	Run a cycle’s lifecycle
GET	/v1/api/cycles/{id}/messages	Read a cycle’s conversation
POST	/v1/api/cycles/{id}/messages	Send a message to a cycle’s coder
GET	/v1/api/cycles/{id}/review	Get the verified review evidence for a cycle
GET	/v1/api/cycles/{id}/review/comments	List the review comments on a cycle
POST	/v1/api/cycles/{id}/review/comments	Comment on a cycle’s review
PATCH	/v1/api/cycles/{id}/review/comments/{commentId}	Resolve or reopen a cycle review comment
POST	/v1/api/cycles/{id}/review/request-revision	Ask the cycle’s build agent to address the open comments
POST	/v1/api/cycles/{id}/stop	Stop a running cycle
POST	/v1/api/cycles/{id}/tasks	Add a task to a cycle
DELETE	/v1/api/cycles/{id}/tasks/{taskId}	Remove a task from a cycle
PATCH	/v1/api/cycles/{id}/tasks/{taskId}	Update a task inside a cycle
GET	/v1/api/cycles/{id}/timeline	List a cycle’s events plus its tasks’
GET	/v1/api/cycles/{id}/usage	Get the cycle’s cost and token roll-up
POST	/v1/api/cycles/direct	Create a separate cycle
POST	/v1/api/cycles/from-branch	Open a cycle from a pushed branch
POST	/v1/api/requests	Submit a request

List cycles

GET /v1/api/cycles · operation ID listCycles

Parameters

Name	In	Required	Type	Description
projectId	query	no	string	Limit results to the specified projects. Repeatable. Explicitly selected projects are included even when archived.
assignedUserId	query	no	string	Only cycles owned by this person. me resolves to the caller.
includeArchived	query	no	string	false hides finished cycles (done, legacy pr_created, failed and canceled). Omit to include all statuses.
orderBy	query	no	string	createdAt (default, newest first) or priority (the Sources Agent’s urgency tier first, ties keep createdAt order).
limit	query	no	string	Page size, 1–500; 200 when omitted. The list is always one page.
before	query	no	string	The id of the last cycle of the previous page: the next, older page. Newest-first order only (not with orderBy=priority). Ask again with the last id until a page comes back shorter than limit.
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	CycleSummary[]	One page of matching cycles, newest first or priority-first with orderBy=priority. Each includes its Linear URL when applicable, owner, project name and whether the caller follows it.
400	ValidationError | ApiError	The query failed schema validation (ValidationError: a limit outside 1–500, or before with orderBy=priority), 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	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Delete a draft or failed cycle

DELETE /v1/api/cycles/{id} · operation ID deleteCycle

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	MessageAck	The cycle was deleted.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	Only a cycle in draft or failed status can be deleted.

Get one cycle with its tasks

GET /v1/api/cycles/{id} · operation ID getCycle

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	CycleDetail	The cycle, its tasks with dependencies, and the live preview URL when one is deployed.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Update a cycle’s title, description or target branch

PATCH /v1/api/cycles/{id} · operation ID updateCycle

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, UpdateCycle (required)

Property	Type	Required	Notes
description	string	no	min length 1, max length 10000
targetBranch	string	no
title	string	no	min length 1, max length 200

Responses

Status	Body	Description
200	Cycle	The updated cycle.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

List a cycle’s approvals

GET /v1/api/cycles/{id}/approvals · operation ID listCycleApprovals

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	Approval[]	This cycle’s requests. Resolved ones are included — status says which are still open.
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.

List a cycle’s stored artifacts

GET /v1/api/cycles/{id}/artifacts · operation ID listCycleArtifacts

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	StoredArtifact[]	The stored objects.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Get a signed download URL for one cycle artifact

GET /v1/api/cycles/{id}/artifacts/{filename} · operation ID getCycleArtifactUrl

Parameters

Name	In	Required	Type	Description
id	path	yes	string
filename	path	yes	string
download	query	no	string	Set to 1 to download artifact bytes when a signed URL cannot be issued. The default JSON response then provides this route with download=1 in its url. When a signed URL is available, the endpoint returns that URL as JSON regardless of this parameter. Other values, including an omitted parameter, return JSON.
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	SignedArtifactUrl	A short-lived signed URL. When the deployment stores artifacts locally, or URL signing is denied, the same field points back at this route with download=1, which answers the object’s own bytes.
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 cycle, or no such artifact under it.
500	ApiError	The artifact download could not be prepared because storage access or URL signing failed. This does not mean the artifact is absent.

Hand a cycle to a teammate

PATCH /v1/api/cycles/{id}/assign · operation ID assignCycle

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, Assign (required)

Property	Type	Required	Notes
userId	string | null	yes

Responses

Status	Body	Description
200	Cycle	The updated cycle. Followers are untouched — handing work over does not drop the people watching it.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
422	ApiError	The assignee is not a member of this workspace.

Admit a branch cycle once its branch is at the pushed commit

POST /v1/api/cycles/{id}/continue · operation ID continueBranchCycle

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	BranchCycleOpened	The cycle is draft and the project loop can dispatch it, or it had already left triage.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	The cycle branch is not at the stored commit, or the cycle changed since it was read.

The cycle’s user-side verification: journeys, outcomes and evidence keys

GET /v1/api/cycles/{id}/e2e · operation ID getCycleE2eReport

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	CycleE2eReport	The e2e report. status: not_run with no journeys when the lane has not verified this cycle.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

List a cycle’s own events

GET /v1/api/cycles/{id}/events · operation ID listCycleEvents

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	ActivityEvent[]	The cycle’s own activity rows, newest 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	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Run a cycle’s lifecycle

POST /v1/api/cycles/{id}/execute · operation ID executeCycle

Parameters

Name	In	Required	Type	Description
id	path	yes	string
mode	query	no	string	machine (default) or desktop.
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	CycleExecutionStarted	The lifecycle run was started. It proceeds asynchronously — watch it on the stream or timeline endpoints.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
402	ApiError	The workspace is over a spend cap — its free monthly credit, its plan’s included usage while extra usage is not allowed for the project, or a limit it set itself. The body names which one and what to do about it.
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 cycle, or its project is gone.
409	ApiError	The cycle’s status does not allow execution.
502	ApiError	The dispatch could not be queued and the cycle was not started. No partial state change was saved; retrying is safe.
503	ApiError	Usage could not be verified, so new spending is paused until the meter is available. Nothing changed.

Read a cycle’s conversation

GET /v1/api/cycles/{id}/messages · operation ID listCycleMessages

Parameters

Name	In	Required	Type	Description
id	path	yes	string
agentId	query	no	string	Read this agent’s thread instead of the cycle’s.
limit	query	no	string	Return only the newest this many messages (1–200). Omit for the full transcript.
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	WireMessage[]	The transcript, oldest first. An unknown cycle or unresolved thread returns an empty list.
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 cycle’s project is out of reach — a client collaborator it was never shared with (existence is deliberately not revealed).

Send a message to a cycle’s coder

POST /v1/api/cycles/{id}/messages · operation ID sendCycleMessage

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, CycleMessage (required)

Property	Type	Required	Notes
agentId	string (uuid) | null	no
attachments	object[]	no
content	string	yes
deliver	boolean	no
messageId	string (uuid)	no
urgent	boolean	no

Responses

Status	Body	Description
202	CycleTurn	The message was stored on the cycle’s conversation, and where it was delivered. No model answers it: a cycle in flight gets it verbatim in the coder’s next turn (urgent: true cancels a running turn so the next one starts now), a ready draft is started, and a finished cycle delivers nothing and tells the project manager. A people-only mention, deliver: false and a replayed messageId are stored only. A client collaborator needs the project’s message grant.
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.
402	ApiError	The workspace is over a spend cap — its free monthly credit, its plan’s included usage while extra usage is not allowed for the project, or a limit it set itself. The body names which one and what to do about it.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	The supplied messageId is already in use — either on another conversation, or on this one with different content.
503	ApiError	Usage could not be verified, so new spending is paused until the meter is available. Nothing changed.

Get the verified review evidence for a cycle

GET /v1/api/cycles/{id}/review · operation ID getCycleReviewEvidence

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	CycleReviewEvidence	A three-dot compare of the cycle branch against the commit it was cut from. While the cycle is in flight the head is the current branch tip; once it is delivered with an approved review, the head is the commit the review approved.
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 cycle, or it has no evidence to show yet (it has not run).
502	ApiError	The repository host could not be reached.

List the review comments on a cycle

GET /v1/api/cycles/{id}/review/comments · operation ID listCycleReviewComments

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	ReviewCommentList	Every comment on the cycle, each marked stale when it was written against an older head than the one the review evidence reports now. When that head cannot be verified, headSha is null and every comment is stale.
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 cycle.

Comment on a cycle’s review

POST /v1/api/cycles/{id}/review/comments · operation ID createCycleReviewComment

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, CreateReviewComment (required)

Property	Type	Required	Notes
body	string	yes	min length 1, max length 10000
headSha	string	yes
lineEnd	integer | null	no
lineStart	integer | null	no
path	string | null	no
selectedText	string | null	no
side	base | head | null	no
visualContext	object	no

Responses

Status	Body	Description
201	ReviewComment	The comment, anchored to the head it names.
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 cycle, or it has no review evidence yet.
409	ApiError	The branch moved on: the comment’s headSha is not the head the review evidence reports now.
413	ApiError	The comment with its visual context is too large.
502	ApiError	The repository host could not be reached.

Resolve or reopen a cycle review comment

PATCH /v1/api/cycles/{id}/review/comments/{commentId} · operation ID updateCycleReviewComment

Parameters

Name	In	Required	Type	Description
id	path	yes	string
commentId	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, UpdateReviewComment (required)

Property	Type	Required	Notes
resolution	open | resolved	yes

Responses

Status	Body	Description
200	ReviewComment	The comment after the change. Setting the resolution it already has changes nothing.
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 cycle, or no such comment on it.

Ask the cycle’s build agent to address the open comments

POST /v1/api/cycles/{id}/review/request-revision · operation ID requestCycleRevision

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, RequestRevision (required)

Property	Type	Required	Notes
headSha	string	yes

Responses

Status	Body	Description
200	ReviewRevisionRequest	The open comments on the reviewed head became one review item on the cycle’s checklist. started is false with reason: waiting_for_build when every build agent is busy: the revision starts on its own once one frees.
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.
402	ApiError	The workspace is over a spend cap — its free monthly credit, its plan’s included usage while extra usage is not allowed for the project, or a limit it set itself. The body names which one and what to do about it.
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 cycle, or it has no review evidence yet.
409	ApiError	The branch moved on, the cycle is running, or there is no open comment on the reviewed head.
502	ApiError	The revision could not be queued. Nothing changed.
503	ApiError	The cycle’s work or retry history could not be read, or usage could not be verified so new spending is paused. Nothing changed.

Stop a running cycle

POST /v1/api/cycles/{id}/stop · operation ID stopCycle

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	CycleStopped	The cycle run moved to canceled. Cancellation takes effect between workflow steps: the current step completes, and subsequent steps do not start. A coding agent already running on a Cloud Machine is not interrupted by this call. projectManagerNotified indicates whether a waiting project run was notified; false is expected for a cycle executed independently.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	There is no running or suspended run to stop; the body names the status that was actually found.

Add a task to a cycle

POST /v1/api/cycles/{id}/tasks · operation ID addCycleTask

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, CreateCycleTask (required)

Property	Type	Required	Notes
dependsOn	string (uuid)[]	no
description	string	yes	min length 1, max length 5000
doneWhen	string	no	min length 1, max length 1000
title	string	yes	min length 1, max length 200

Responses

Status	Body	Description
201	Task	The created task. A finished (done) cycle reopens to run it: it takes a build agent, or waits as a ready draft while every build agent is busy.
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.
402	ApiError	The workspace is over a spend cap — its free monthly credit, its plan’s included usage while extra usage is not allowed for the project, or a limit it set itself. The body names which one and what to do about it.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	The project is archived or paused, or the cycle was stopped, so it does not accept new tasks.
503	ApiError	Usage could not be verified, so new spending is paused until the meter is available. Nothing changed.

Remove a task from a cycle

DELETE /v1/api/cycles/{id}/tasks/{taskId} · operation ID deleteCycleTask

Parameters

Name	In	Required	Type	Description
id	path	yes	string
taskId	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	MessageAck	The task was deleted.
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 under this cycle.
409	ApiError	Only a task in queued or blocked status can be deleted.

Update a task inside a cycle

PATCH /v1/api/cycles/{id}/tasks/{taskId} · operation ID updateCycleTask

Parameters

Name	In	Required	Type	Description
id	path	yes	string
taskId	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, UpdateCycleTask (required)

Property	Type	Required	Notes
description	string	no	min length 1, max length 5000
doneWhen	string | null	no
sortOrder	integer	no	min -9007199254740991, max 9007199254740991
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 under this cycle.

List a cycle’s events plus its tasks’

GET /v1/api/cycles/{id}/timeline · operation ID getCycleTimeline

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	ActivityEvent[]	The cycle’s activity rows merged with its tasks’, 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	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Get the cycle’s cost and token roll-up

GET /v1/api/cycles/{id}/usage · operation ID getCycleUsage

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	AgentUsageRollup	Totals with breakdowns by execution lane (byRole) and worker promptKey (byPromptKey). Lanes without runs are omitted. byPromptKey includes a null bucket for runs without an assigned promptKey. Both breakdowns sum to totals.
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 cycle in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Create a separate cycle

POST /v1/api/cycles/direct · operation ID createDirectCycle

Authentication — A signed-in user session is required. API keys cannot authenticate this operation. Browsers send the session cookie automatically; server clients preserve the complete issued Cookie header.

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, DirectCycle (required)

Property	Type	Required	Notes
description	string	yes	min length 1, max length 10000
projectId	string (uuid)	yes
title	string	yes	min length 1, max length 200

Responses

Status	Body	Description
201	Cycle	The committed cycle, with trusted human origin. Normal planning and dispatch gates still apply.
400	ValidationError	Invalid fields; author, agent-run identity and unsupported options are not accepted.
401	ApiError	No valid session or API key.
403	ApiError	A client, API key or task credential cannot create a human-authored cycle.
404	ApiError	No accessible project in this workspace.
409	DirectCycleConflict	Duplicate title has code CYCLE_DUPLICATE_TITLE; other conflicts indicate changed project context or sources policy. Retain the brief and show the error.

Open a cycle from a pushed branch

POST /v1/api/cycles/from-branch · operation ID openBranchCycle

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, OpenBranchCycle (required)

Property	Type	Required	Notes
branch	string	yes	min length 1, max length 200
commit	string	yes
projectId	string (uuid)	yes

Responses

Status	Body	Description
200	BranchCycleOpened	The cycle that continues that commit. branch is the cycle branch the work pushes to. An existing cycle for the same commit, or an open cycle for the same branch, is returned as it stands.
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 has no single repository to continue on, or the branch or commit was rejected.

Submit a request

POST /v1/api/requests · operation ID submitRequest

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, CreateCycle (required)

Property	Type	Required	Notes
attachments	object[]	no
description	string	yes	min length 1, max length 10000
projectId	string (uuid)	yes
targetBranch	string	no
title	string	yes	min length 1, max length 200

Responses

Status	Body	Description
202	RequestSubmitted	The proposal was recorded. cycleId is the cycle the plan agent made of it when it planned before answering (the normal case); null means it is still waiting for a planning pass, and requestId is the row to follow. adopted: false means the proposal could not be recorded.
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 or this request source is disabled. The response explains how to allow work again.

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. 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 — 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

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.