Projects

A project groups a delivery goal, its roadmap, repositories, Project Environment and budget. These operations create and configure projects, start work, and read delivery progress and Cloud Machine access.

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/projects	List the workspace’s projects
POST	/v1/api/projects	Create a project
DELETE	/v1/api/projects/{id}	Delete a project
GET	/v1/api/projects/{id}	Get one project
PATCH	/v1/api/projects/{id}	Update a project’s configuration
GET	/v1/api/projects/{id}/architecture	Read the application’s source dependency graph
POST	/v1/api/projects/{id}/archive	Archive a project
GET	/v1/api/projects/{id}/artifacts	List a project’s stored artifacts
GET	/v1/api/projects/{id}/artifacts/{filename}	Get a signed download URL for one project artifact
PATCH	/v1/api/projects/{id}/assign	Hand a project to a teammate
GET	/v1/api/projects/{id}/board	Read the rows a project’s board shows
GET	/v1/api/projects/{id}/budget	Get the project’s delivery budget and spend to date
GET	/v1/api/projects/{id}/canvas	Read the project canvas without waking its Cloud Machine
GET	/v1/api/projects/{id}/canvas/agent	Read the project canvas as an agent may see it
POST	/v1/api/projects/{id}/canvas/agent/ops	Draw on the project canvas as hlix, for the caller
POST	/v1/api/projects/{id}/canvas/agent/undo	Undo hlix’s most recent canvas edit
GET	/v1/api/projects/{id}/chats	Get the project’s conversation tree
GET	/v1/api/projects/{id}/cycle-metrics	Get a project’s flow metrics computed from cycle stage history
POST	/v1/api/projects/{id}/delivery	Open the project’s pull request now
GET	/v1/api/projects/{id}/desktops	List the project’s Desktops
GET	/v1/api/projects/{id}/desktops/{desktopId}	Read one Desktop and the links to its screen
POST	/v1/api/projects/{id}/desktops/{desktopId}/control	Take control of a Desktop, or give it back
GET	/v1/api/projects/{id}/desktops/{desktopId}/evidence/{kind}	Download the screen or replay a finished run kept
POST	/v1/api/projects/{id}/detect-commands	Re-run command detection without writing anything
GET	/v1/api/projects/{id}/diagnostics	Read why a project failed or is waiting
GET	/v1/api/projects/{id}/director	Watch the Director Explainer’s evolving video segments
GET	/v1/api/projects/{id}/director/clips/{clipId}	Read an audience-scoped Director video segment
GET	/v1/api/projects/{id}/environment	Read the project’s saved Cloud Machine environment
POST	/v1/api/projects/{id}/environment/keepalive	Tell a running environment it is still in use
POST	/v1/api/projects/{id}/environment/rebuild	Build the project’s environment again
GET	/v1/api/projects/{id}/image-builds	List the project’s Cloud Machine image builds
GET	/v1/api/projects/{id}/initial-proposal	Read the current initial SDD/SOW
POST	/v1/api/projects/{id}/initial-proposal/approve	Approve the initial plan and release delivery
GET	/v1/api/projects/{id}/initial-proposal/comments	List section-anchored proposal comments
POST	/v1/api/projects/{id}/initial-proposal/comments	Comment on a proposal section
PATCH	/v1/api/projects/{id}/initial-proposal/comments/{commentId}	Resolve or reopen a proposal comment
POST	/v1/api/projects/{id}/initial-proposal/decision	Record the invited client review agent’s optional decision
GET	/v1/api/projects/{id}/initial-proposal/logo	Read the frozen agency logo
POST	/v1/api/projects/{id}/initial-proposal/publish	Publish a branded proposal revision
GET	/v1/api/projects/{id}/initial-proposal/revisions	List proposal revision history
POST	/v1/api/projects/{id}/initial-proposal/revisions	Request a targeted AI revision
PUT	/v1/api/projects/{id}/initial-proposal/revisions/manual	Create a manual business-copy revision
GET	/v1/api/projects/{id}/insights	Get a project’s Cloud Machine totals and estimated completion
GET	/v1/api/projects/{id}/linear-sessions	List the Linear conversations delegated into this project
GET	/v1/api/projects/{id}/messages	Read the project’s conversation
POST	/v1/api/projects/{id}/mobile/agent-sessions	Start a native test device for this agent run
DELETE	/v1/api/projects/{id}/mobile/agent-sessions/{sessionId}	Stop this agent run’s native test device
GET	/v1/api/projects/{id}/mobile/agent-sessions/{sessionId}	Read this agent run’s native test device
GET	/v1/api/projects/{id}/mobile/builds	List saved native builds
POST	/v1/api/projects/{id}/mobile/builds	Build a native app preview
POST	/v1/api/projects/{id}/mobile/sessions	Start a private app preview
DELETE	/v1/api/projects/{id}/mobile/sessions/{sessionId}	End your private app preview
GET	/v1/api/projects/{id}/mobile/sessions/{sessionId}	Read your private app preview
GET	/v1/api/projects/{id}/mobile/targets	List native app targets
PUT	/v1/api/projects/{id}/mobile/targets	Configure native app targets
GET	/v1/api/projects/{id}/repos	List a project’s repositories
POST	/v1/api/projects/{id}/repos	Attach a repository to a project
DELETE	/v1/api/projects/{id}/repos/{repoId}	Detach a repository from a project
PATCH	/v1/api/projects/{id}/repos/{repoId}	Update a repository’s branch or label
POST	/v1/api/projects/{id}/repos/{repoId}/primary	Make a repository the project’s primary
POST	/v1/api/projects/{id}/repos/github	Attach an existing GitHub repository by owner/name
POST	/v1/api/projects/{id}/resume	Resume a stopped project, or start one that never started
GET	/v1/api/projects/{id}/review	Read recorded verification evidence for completed project cycles
POST	/v1/api/projects/{id}/review/merge	Merge a reviewed preview pull request at its exact head commit
GET	/v1/api/projects/{id}/roadmap	Get the project’s roadmap
GET	/v1/api/projects/{id}/sequence	Watch a cycle’s narrated Sequence
POST	/v1/api/projects/{id}/start	Start the project’s autonomous run
GET	/v1/api/projects/{id}/status	Read a project’s delivery status
POST	/v1/api/projects/{id}/stop	Stop every agent working on the project
POST	/v1/api/projects/{id}/suggest-stack	Propose a stack string from the project’s own evidence
GET	/v1/api/projects/{id}/terminal	Open a shell into the project’s Cloud Machine
POST	/v1/api/projects/{id}/unarchive	Restore an archived project
GET	/v1/api/projects/{id}/usage	Get the project’s cost and token roll-up
POST	/v1/api/projects/{id}/workspace/exec	Run a command in the project’s Cloud Machine
POST	/v1/api/projects/{id}/workspace/fs	Read or write a file in the project’s Cloud Machine
GET	/v1/api/projects/{projectId}/designs	List native project designs
POST	/v1/api/projects/{projectId}/designs	Submit a native prototype brief
GET	/v1/api/projects/{projectId}/designs/{designId}	Read a design revision and its review threads
POST	/v1/api/projects/{projectId}/designs/{designId}/build	Submit implementation of an accepted prototype
POST	/v1/api/projects/{projectId}/designs/{designId}/comments	Comment on a frame without dispatching work
PATCH	/v1/api/projects/{projectId}/designs/{designId}/comments/{commentId}	Resolve or reopen a design comment
POST	/v1/api/projects/{projectId}/designs/{designId}/decisions	Accept a revision or submit revision work
POST	/v1/api/projects/{projectId}/designs/{designId}/revisions	Publish a tested playable prototype
GET	/v1/api/projects/initial-proposal-by-id/{proposalId}	Resolve a proposal deep link

List the workspace’s projects

GET /v1/api/projects · operation ID listProjects

Parameters

Name	In	Required	Type	Description
includeArchived	query	no	string	Set to true to include archived projects. They are hidden by default.
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	ProjectSummary[]	Active projects by default, newest first, each with attached repositories and index counts. includeArchived=true adds archived projects.
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 project

POST /v1/api/projects · operation ID createProject

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

Property	Type	Required	Notes
attachments	object[]	no
brief	string	no	min length 1, max length 5000
claudeMd	string	no
githubRepository	string	no	max length 301
initialProposalRequired	boolean	no	Hold the first build until a person approves the plan. Defaults to false: hlix starts by itself.
name	string	no	min length 1, max length 100
repos	object[]	no
runtime	object	no
stack	string	no	min length 1, max length 200
tier	auto | frontier | frontierMax | ownSubscription	no
useWorkspaceBrand	boolean	no

Responses

Status	Body	Description
201	Project	The created project and its repositories.
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 on the free plan and already holds its maximum number of active projects. Upgrade, or archive one.
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.
409	ApiError	One of the named repositories is already attached to another project in this workspace.
422	ApiError	githubRepository, or a repository in repos, is not reachable through this workspace’s GitHub connection (none, revoked, or not granted that repository): code is github_repository_unreachable. Or a repository’s defaultBranch does not exist there: code is default_branch_missing. A repository sent without defaultBranch stores the one the repository names. Nothing was created.
500	ApiError	The project could not be created.

Delete a project

DELETE /v1/api/projects/{id} · operation ID deleteProject

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 project 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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Get one project

GET /v1/api/projects/{id} · operation ID getProject

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	ProjectDetail	The project, its repositories, the viewer’s message permission and whether this deployment can publish previews.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Update a project’s configuration

PATCH /v1/api/projects/{id} · operation ID updateProject

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

Property	Type	Required	Notes
branchPrefix	string | null	no
brief	string | null	no
claudeMd	string	no
costCapMicros	integer (int64) | null	no
cycleCap	integer | null	no
initialProposalRequired	boolean	no
machineSize	small | standard | large | null	no
maxRevisions	integer | null	no
name	string	no	min length 1, max length 100
previewCommand	string | null	no
previewPort	integer | null	no
runtime	object	no
sources	object	no
stack	string	no	min length 1, max length 200
tier	auto | frontier | frontierMax | ownSubscription | null	no
useWorkspaceBrand	boolean	no
verifyCommand	string | null	no

Responses

Status	Body	Description
200	Project	The updated project. Repository membership is never changed here — the collection is echoed back unchanged.
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	branchPrefix was sent but the project’s preview branch has already been cut, so its prefix can no longer change (code branch_prefix_locked), or useWorkspaceBrand was set before the workspace brand kit is published. Nothing changed.
422	ApiError	branchPrefix names a branch that already exists in one of the project’s repositories, so no branch could be created under it (code branch_prefix_taken). Nothing changed.
502	ApiError	A repository’s host could not be reached to check branchPrefix against its branches (code repository_unreachable). Nothing changed.

Read the application’s source dependency graph

GET /v1/api/projects/{id}/architecture · operation ID getProjectArchitecture

Parameters

Name	In	Required	Type	Description
id	path	yes	string
cycleId	query	no	string	Optional cycle UUID belonging to this project; scopes changed paths and recorded aggregate checks.
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	ApplicationArchitecture	Bounded static JavaScript/TypeScript imports and declared package dependencies. Repository source files are read at the resolved commit; a running task’s changes are read from its worktree against the commit it was cut from, so they can include uncommitted edits. No customer code, macros or builds are executed, and no Cloud Machine is created or woken. Coverage and warning codes report unsupported, unresolved, unavailable or truncated analysis. Checks belong to the selected cycle, never to an individual component.
400	ApiError	Malformed cycle UUID.
401	ApiError	No valid session or API key.
403	ApiError	Source browsing is restricted to the agency.
404	ApiError	Project or selected cycle not found in this project.
504	ApiError	Source analysis did not answer before its deadline.

Archive a project

POST /v1/api/projects/{id}/archive · operation ID archiveProject

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	Project	The project was archived and is now hidden from default lists.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

List a project’s stored artifacts

GET /v1/api/projects/{id}/artifacts · operation ID listProjectArtifacts

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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Get a signed download URL for one project artifact

GET /v1/api/projects/{id}/artifacts/{filename} · operation ID getProjectArtifactUrl

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 project, 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 project to a teammate

PATCH /v1/api/projects/{id}/assign · operation ID assignProject

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	ProjectRow	The updated project row (no repository collection — this endpoint changes ownership only).
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).
422	ApiError	The assignee is not a member of this workspace.

Read the rows a project’s board shows

GET /v1/api/projects/{id}/board · operation ID getProjectBoard

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	ProjectBoard	The project’s status and stop state, its cycles with their dependencies, the build agent run at work on each, the checklist, the agents at work and the deployed preview. ?cycleId= or ?taskId= narrows it to that slice. Requires view access; client collaborator responses are redacted. Refresh it when the workspace live socket (GET /v1/api/live) announces a change.
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 project in this workspace — or a client collaborator it was never shared with, or a cycle or task outside the project.

Get the project’s delivery budget and spend to date

GET /v1/api/projects/{id}/budget · operation ID getProjectBudget

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	ProjectBudget	The project’s own cap overrides (null means inherited), the caps actually enforced, the platform defaults behind them, and spend to date in USD.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Read the project canvas without waking its Cloud Machine

GET /v1/api/projects/{id}/canvas · operation ID getProjectCanvas

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	ProjectCanvas	Repository, runtime, sources and activity observations.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Read the project canvas as an agent may see it

GET /v1/api/projects/{id}/canvas/agent · operation ID getCanvasAgentView

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	CanvasAgentView	Every element marked as project context and everything hlix drew, with positions; people’s unmarked work only as empty rectangles.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	The canvas needs builder access for portal clients.
404	ApiError	Project not found.

Draw on the project canvas as hlix, for the caller

POST /v1/api/projects/{id}/canvas/agent/ops · operation ID applyCanvasAgentOps

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

Property	Type	Required	Notes
ops	object | object | object[]	yes
reason	string	no	max length 300

Responses

Status	Body	Description
200	CanvasAgentWrite	Changes applied as one batch, attributed to Hlix on behalf of the caller and broadcast to canvas viewers. When the changes affect project context and automatic application is disabled, the batch is saved as a suggestion with applied: false and a approvalId for acceptance or rejection.
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	The canvas needs builder access for portal clients.
404	ApiError	Project not found.
422	ApiError	Refused as a whole: the batch touches something not shared with hlix, sets the project context mark, or is not a valid canvas change.

Undo hlix’s most recent canvas edit

POST /v1/api/projects/{id}/canvas/agent/undo · operation ID undoCanvasAgentEdit

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	CanvasAgentUndo	Whether an edit of hlix’s was undone; people’s own edits are never undone here.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	The canvas needs builder access for portal clients.
404	ApiError	Project not found.
422	ApiError	People have since changed what that edit touched, so it cannot be reversed cleanly.

Get the project’s conversation tree

GET /v1/api/projects/{id}/chats · operation ID getProjectChatDirectory

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	ProjectChatDirectory	The thread directory, including whether its result is authoritative. A degraded lookup is explicitly marked rather than reported as an authoritative empty directory.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Get a project’s flow metrics computed from cycle stage history

GET /v1/api/projects/{id}/cycle-metrics · operation ID getProjectCycleMetrics

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	CycleMetrics	Throughput, cycle-time percentiles, per-stage medians, WIP, aging WIP, and stage-automation quality computed from each cycle’s stageHistory, plus per-cycle model calls, tokens, cost, Cloud Machine starts and time per stage.
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 project in this workspace.

Open the project’s pull request now

POST /v1/api/projects/{id}/delivery · operation ID requestProjectDelivery

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	ProjectDelivery	The project’s preview → main pull request, found or created. This operation does not merge it; a person must approve the final merge. url is null when the preview branch has no changes ahead of the default branch.
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 project in this workspace — or a caller it was never shared with.
409	ApiError	There is no pull request to open yet: Hlix is still building or checking the project, or it has several repositories and none is marked primary. The error says which, and what to do.

List the project’s Desktops

GET /v1/api/projects/{id}/desktops · operation ID listDesktops

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	Desktops	The project’s own Desktop (project) first, then the Desktop of each build agent run, newest first, each with its observed presence: live (its machine is running and a build agent is working on it now), idle (running, nothing working on it), ended (its machine is gone) or off (the project’s own Desktop is not running). Each says who has control: a person, or null for the build agent. Also whether the project’s hosted app is up. Agency members only.
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	Project not found.

Read one Desktop and the links to its screen

GET /v1/api/projects/{id}/desktops/{desktopId} · operation ID getDesktop

Parameters

Name	In	Required	Type	Description
id	path	yes	string
desktopId	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	Desktop	The Desktop’s state and, when its screen is up, the frame links. Reading the project’s own Desktop starts its Cloud Machine unless the project is archived (state: starting while it comes up; poll). Reading a build agent’s Desktop starts nothing. Ended Desktops never attach to a new run.
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	Desktop not found in this project.

Take control of a Desktop, or give it back

POST /v1/api/projects/{id}/desktops/{desktopId}/control · operation ID controlDesktop

Parameters

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

Property	Type	Required	Notes
action	take | give_back	yes

Responses

Status	Body	Description
200	DesktopControlResult	Who has control after the call. While a person has control the build agent’s actions answer that it must wait; giving control back, closing the person’s screen connection or letting it lapse returns control to the 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	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.
409	ApiError	Another person has control, or the Desktop is not running, or the project is archived.

Download the screen or replay a finished run kept

GET /v1/api/projects/{id}/desktops/{desktopId}/evidence/{kind} · operation ID downloadDesktopEvidence

Parameters

Name	In	Required	Type	Description
id	path	yes	string
desktopId	path	yes	string
kind	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 (binary)	Authenticated retained screen (kind=screen) or recording (kind=replay). Missing evidence is never fabricated.
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	Desktop evidence not found.
409	ApiError	The Desktop is not accessible in this project.

Re-run command detection without writing anything

POST /v1/api/projects/{id}/detect-commands · operation ID detectProjectCommands

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

The contract does not pin this body’s properties.

Responses

Status	Body	Description
200	ProjectCommandDetection	Install, preview and verification commands detected from committed repository files. Does not write settings or wake a Cloud Machine.
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	Growth projects run campaigns and have no application stack or Cloud Machine to read or provision.

Read why a project failed or is waiting

GET /v1/api/projects/{id}/diagnostics · operation ID getProjectRunDiagnostics

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	ProjectDiagnostics	Current project delivery diagnostics: the next planned action, work in progress and work waiting at an approval checkpoint. Computed from the project’s current cycles and state.
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 project in this workspace.

Watch the Director Explainer’s evolving video segments

GET /v1/api/projects/{id}/director · operation ID watchProjectDirector

Parameters

Name	In	Required	Type	Description
id	path	yes	string
cycleId	query	no	string	Selected chapter
language	query	no	string	en, de or fr
retry	query	no	string	1 to retry a failed render after automatic retries are exhausted
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	DirectorState	Audience-scoped rendered segments. Polling requests new evidence-based footage; unchanged evidence reuses the existing video. Rendering is asynchronous and failures retain previous footage.
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	Project not found

Read an audience-scoped Director video segment

GET /v1/api/projects/{id}/director/clips/{clipId} · operation ID getProjectDirectorClip

Parameters

Name	In	Required	Type	Description
id	path	yes	string
clipId	path	yes	string
cycleId	query	no	string	Selected chapter
language	query	no	string	en, de or fr
download	query	no	string	1 for authenticated video bytes when no signed URL is available
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	SignedArtifactUrl	Signed media URL, or authenticated video bytes for local artifacts.
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	Project or clip not found

Read the project’s saved Cloud Machine environment

GET /v1/api/projects/{id}/environment · operation ID getProjectEnvironment

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	ProjectEnvironment	The saved environment: none (Cloud Machines start from the base image), building, ready (Cloud Machines start from the snapshot captured at createdAt), or local for the local runtime. This read starts no Cloud Machine or build. workspaceRoot is the primary repository checkout and the shell working directory.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Tell a running environment it is still in use

POST /v1/api/projects/{id}/environment/keepalive · operation ID keepProjectEnvironmentAlive

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	ProjectEnvironmentKeepAlive	kept: true means the environment was already running and its idle timeout was refreshed. This endpoint never starts or resumes a Cloud Machine. Stopped, absent or unreachable environments return kept: false with their state. Terminal, Desktop and Preview clients can use this while active. Provider updates are limited to one per project per 60 seconds; requests within that window reuse the last result.
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 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 work — refused before the environment was even looked up.

Build the project’s environment again

POST /v1/api/projects/{id}/environment/rebuild · operation ID rebuildProjectEnvironment

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
202	ProjectEnvironmentRebuild	The setup is under way (started), or one is already open and this ask builds again once it ends (waiting). Never two at once.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Only workspace members may rebuild an environment; a client never may.
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 it is stopped: Resume it first, then ask again.

List the project’s Cloud Machine image builds

GET /v1/api/projects/{id}/image-builds · operation ID listProjectImageBuilds

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	ProjectImageBuild[]	The build 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	No such project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Read the current initial SDD/SOW

GET /v1/api/projects/{id}/initial-proposal · operation ID getProjectInitialProposal

Parameters

Name	In	Required	Type	Description
id	path	yes	string
revision	query	no	string	Revision number to read; agency only. Clients always receive the published revision.
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	InitialProposalDetailResponse	The current proposal and revision.
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 proposal in this workspace — or the caller may not see it.

Approve the initial plan and release delivery

POST /v1/api/projects/{id}/initial-proposal/approve · operation ID approveProjectInitialProposal

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

Property	Type	Required	Notes
contentHash	string	yes	min length 64, max length 64
revisionId	string	yes	min length 1

Responses

Status	Body	Description
200	InitialProposal	The approved proposal, with its Canvas batch and durable release.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

List section-anchored proposal comments

GET /v1/api/projects/{id}/initial-proposal/comments · operation ID listProjectInitialProposalComments

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	InitialProposalCommentsResponse	One bounded keyset page of comments.
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 proposal in this workspace — or the caller may not see it.

Comment on a proposal section

POST /v1/api/projects/{id}/initial-proposal/comments · operation ID addProjectInitialProposalComment

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

Property	Type	Required	Notes
blockId	string	yes	min length 1, max length 120
body	string	yes	min length 1, max length 10000
parentId	string | null	yes
revisionHash	string	yes
revisionId	string	yes	min length 1, max length 120
selectedText	string | null	yes

Responses

Status	Body	Description
201	InitialProposalComment	The new comment.
400	ValidationError | ApiError	The request is invalid.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

Resolve or reopen a proposal comment

PATCH /v1/api/projects/{id}/initial-proposal/comments/{commentId} · operation ID resolveProjectInitialProposalComment

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.

Request body — application/json, InitialProposalResolveComment (required)

Property	Type	Required	Notes
resolved	boolean	yes

Responses

Status	Body	Description
200	InitialProposalComment	The updated 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 proposal in this workspace — or the caller may not see it.

Record the invited client review agent’s optional decision

POST /v1/api/projects/{id}/initial-proposal/decision · operation ID decideProjectInitialProposal

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

Property	Type	Required	Notes
comment	string | null	yes
decision	approved | changes_requested	yes
revisionHash	string	yes
revisionId	string	yes	min length 1, max length 120

Responses

Status	Body	Description
200	InitialProposal	The proposal with the client decision.
400	ValidationError | ApiError	The request is invalid.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

Read the frozen agency logo

GET /v1/api/projects/{id}/initial-proposal/logo · operation ID getProjectInitialProposalLogo

Parameters

Name	In	Required	Type	Description
id	path	yes	string
revisionId	query	no	string	Revision whose frozen logo should be read; clients must name the published revision.
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	string (binary)	The validated PNG logo for the published revision.
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 proposal in this workspace — or the caller may not see it.

Publish a branded proposal revision

POST /v1/api/projects/{id}/initial-proposal/publish · operation ID publishProjectInitialProposal

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

Property	Type	Required	Notes
clientReviewerId	string | null	no
visibility	internal | client	no

Responses

Status	Body	Description
200	InitialProposalDetailResponse	The published revision with a frozen brand snapshot.
400	ValidationError | ApiError	The request is invalid.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

List proposal revision history

GET /v1/api/projects/{id}/initial-proposal/revisions · operation ID listProjectInitialProposalRevisions

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	InitialProposalHistoryResponse	Up to 50 revisions, newest first; clients receive only the published revision.
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 proposal in this workspace — or the caller may not see it.

Request a targeted AI revision

POST /v1/api/projects/{id}/initial-proposal/revisions · operation ID reviseProjectInitialProposal

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

Property	Type	Required	Notes
baseHash	string	yes	min length 64, max length 64
baseRevisionId	string	yes	min length 1
commentIds	string[]	no
instruction	string	yes	min length 1, max length 12000

Responses

Status	Body	Description
202	InitialProposalRevision	The durable revision job.
400	ValidationError | ApiError	The request is invalid.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

Create a manual business-copy revision

PUT /v1/api/projects/{id}/initial-proposal/revisions/manual · operation ID editProjectInitialProposal

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

Property	Type	Required	Notes
baseHash	string	yes	min length 64, max length 64
baseRevisionId	string	yes	min length 1
blocks	object | object | object[]	yes

Responses

Status	Body	Description
200	InitialProposalRevision	The new immutable revision.
400	ValidationError | ApiError	The request is invalid.
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 proposal in this workspace — or the caller may not see it.
409	ApiError	The proposal changed. Reload the current revision and retry.

Get a project’s Cloud Machine totals and estimated completion

GET /v1/api/projects/{id}/insights · operation ID getProjectTeamInsights

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	ProjectTeamInsights	Cloud Machine starts and runtime hours, completed agent runs, and an estimated completion range. The estimate is null until enough delivered cycles are available.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	A client whose seat was not given the project insights view.
404	ApiError	No such project in this workspace.

List the Linear conversations delegated into this project

GET /v1/api/projects/{id}/linear-sessions · operation ID listProjectLinearSessions

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	ProjectLinearSessions	Sessions, newest first, with the Linear issue identifier and URL, session status, and linked cycle. The cycle is null until the project manager adopts the session.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Read the project’s conversation

GET /v1/api/projects/{id}/messages · operation ID listProjectMessages

Parameters

Name	In	Required	Type	Description
id	path	yes	string
agentId	query	no	string	Read this agent’s project thread instead of the project manager’s.
limit	query	no	string	How many stored turns one page holds, 1 to 200. Default 50.
before	query	no	string	The nextCursor of the page you have: read the turns older than it.
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	WireMessagePage	The newest turns, or the turns older than before, ordered oldest first, with a cursor for older results. An unresolved project or agent thread returns an empty page.
400	ValidationError	limit or before failed validation.
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).

Start a native test device for this agent run

POST /v1/api/projects/{id}/mobile/agent-sessions · operation ID startProjectMobileAgentSession

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

Property	Type	Required	Notes
buildId	string (uuid)	yes
requestId	string (uuid)	yes

Responses

Status	Body	Description
200	MobileAgentSession	Instance access for the authenticated agent run only
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Stop this agent run’s native test device

DELETE /v1/api/projects/{id}/mobile/agent-sessions/{sessionId} · operation ID stopProjectMobileAgentSession

Parameters

Name	In	Required	Type	Description
id	path	yes	string
sessionId	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	MobileStopped	Cleanup requested
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Read this agent run’s native test device

GET /v1/api/projects/{id}/mobile/agent-sessions/{sessionId} · operation ID getProjectMobileAgentSession

Parameters

Name	In	Required	Type	Description
id	path	yes	string
sessionId	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	MobileAgentSession	Instance access for the authenticated agent run only
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

List saved native builds

GET /v1/api/projects/{id}/mobile/builds · operation ID getProjectMobileBuilds

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	MobileBuildsView	Build history
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Build a native app preview

POST /v1/api/projects/{id}/mobile/builds · operation ID buildProjectMobileApp

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

Property	Type	Required	Notes
expectedCommitSha	string	no	Require this exact published revision. An unpublished revision returns 409 source_not_published without creating a build.
targetId	string	yes

Responses

Status	Body	Description
202	MobileBuild	Build queued at the source revision
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	Workspace credit is exhausted
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Start a private app preview

POST /v1/api/projects/{id}/mobile/sessions · operation ID startProjectMobileSession

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

Property	Type	Required	Notes
buildId	string (uuid)	yes
tabId	string (uuid)	yes

Responses

Status	Body	Description
200	MobileSession	Private viewer session; poll while creating
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	Workspace credit is exhausted
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

End your private app preview

DELETE /v1/api/projects/{id}/mobile/sessions/{sessionId} · operation ID stopProjectMobileSession

Parameters

Name	In	Required	Type	Description
id	path	yes	string
sessionId	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	MobileStopped	Cleanup requested
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Read your private app preview

GET /v1/api/projects/{id}/mobile/sessions/{sessionId} · operation ID getProjectMobileSession

Parameters

Name	In	Required	Type	Description
id	path	yes	string
sessionId	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	MobileSession	Viewer session and streaming credential
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

List native app targets

GET /v1/api/projects/{id}/mobile/targets · operation ID getProjectMobileTargets

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	MobileTargetsView	Configured app targets
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

Configure native app targets

PUT /v1/api/projects/{id}/mobile/targets · operation ID setProjectMobileTargets

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

Property	Type	Required	Notes
targets	object[]	yes

Responses

Status	Body	Description
200	MobileTargetsSaved	Saved targets
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	Project or mobile resource not found
409	ApiError	Project or build is not ready
503	ApiError	Mobile provider is unavailable

List a project’s repositories

GET /v1/api/projects/{id}/repos · operation ID listProjectRepos

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	ProjectRepo[]	The repositories, primary first then 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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Attach a repository to a project

POST /v1/api/projects/{id}/repos · operation ID attachProjectRepo

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

Property	Type	Required	Notes
cloneUrl	string (uri)	yes
defaultBranch	string	no	min length 1, max length 200
githubInstallationId	string | null	no
githubRepoId	integer | null	no
isPrimary	boolean	no
label	string | null	no
name	string	yes	min length 1, max length 200
owner	string	yes	min length 1, max length 100
provider	string	no

Responses

Status	Body	Description
201	ProjectRepo	The attached repository.
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	That repository is already attached to a project in this workspace, or the project is a growth project, which runs campaigns and takes no GitHub repository.
422	ApiError	This workspace’s GitHub connection cannot reach that repository (code github_repository_unreachable), or defaultBranch does not exist there (code default_branch_missing). Without defaultBranch the repository’s own default branch is stored. Nothing changed.
500	ApiError	The repository could not be attached.

Detach a repository from a project

DELETE /v1/api/projects/{id}/repos/{repoId} · operation ID detachProjectRepo

Parameters

Name	In	Required	Type	Description
id	path	yes	string
repoId	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 repository was detached.
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 project, or that repository does not belong to it.
409	ApiError	Tasks have already run against that repository, so it cannot be detached.

Update a repository’s branch or label

PATCH /v1/api/projects/{id}/repos/{repoId} · operation ID updateProjectRepo

Parameters

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

Property	Type	Required	Notes
defaultBranch	string	no	min length 1, max length 200
label	string | null	no
previewCommand	string | null	no
previewPort	integer | null	no
setupCommand	string | null	no
verifyCommand	string | null	no

Responses

Status	Body	Description
200	ProjectRepo	The updated repository. A changed defaultBranch also moves the project’s open review pull request onto 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 project, or that repository does not belong to it.
409	ApiError	The repository is being connected; retry when it finishes.
422	ApiError	defaultBranch does not exist in the repository (code default_branch_missing). Nothing changed.
502	ApiError	The repository could not be read to check defaultBranch (code repository_unreachable), or the open review pull request could not be moved onto it (code review_pull_request_not_moved). Nothing changed.

Make a repository the project’s primary

POST /v1/api/projects/{id}/repos/{repoId}/primary · operation ID setPrimaryProjectRepo

Parameters

Name	In	Required	Type	Description
id	path	yes	string
repoId	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	ProjectRepo	The promoted repository, or connectionStatus connecting while existing managed work is transferred to GitHub.
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 project, or that repository does not belong to it.
409	ApiError	Another repository connection is in progress.

Attach an existing GitHub repository by owner/name

POST /v1/api/projects/{id}/repos/github · operation ID attachProjectGithubRepository

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

Property	Type	Required	Notes
githubRepository	string	yes	max length 301

Responses

Status	Body	Description
200	ProjectRepo	The repository was already attached to this project; nothing changed.
201	ProjectRepo	The attached repository, resolved through this workspace’s GitHub connection. It is the primary only when the project had none. Its history is left as it is.
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	That repository is attached to another project in this workspace (code repository_on_another_project, with that projectId), or is still being connected, or the project is a growth project, which runs campaigns and takes no GitHub repository. Nothing changed.
422	ApiError	This workspace’s GitHub connection cannot reach that repository (none, revoked, or not granted it). code is github_repository_unreachable; nothing changed.

Resume a stopped project, or start one that never started

POST /v1/api/projects/{id}/resume · operation ID resumeProject

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	ProjectResumed	The project continues where it stopped: stopped work is queued again and the project’s own loop takes it from there. A project that never started is started with its brief. Resuming a running project answers its state.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
402	ApiError	The workspace has no credit left for new agent work.
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 stop is still draining, or the project is idle with nothing to resume. The body names the status.

Read recorded verification evidence for completed project cycles

GET /v1/api/projects/{id}/review · operation ID getProjectReview

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	ProjectReview	Observed journey outcomes and verification counts.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Merge a reviewed preview pull request at its exact head commit

POST /v1/api/projects/{id}/review/merge · operation ID mergeProjectReview

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

Property	Type	Required	Notes
headSha	string	yes
repoId	string (uuid)	yes

Responses

Status	Body	Description
200	MessageAck	GitHub confirmed the merge.
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 review changed or the project is archived.

Get the project’s roadmap

GET /v1/api/projects/{id}/roadmap · operation ID getProjectRoadmap

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	ProjectRoadmap	The combined roadmap: saved cycles, the project manager’s plan, and pending or recently resolved proposals.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Watch a cycle’s narrated Sequence

GET /v1/api/projects/{id}/sequence · operation ID getProjectSequence

Parameters

Name	In	Required	Type	Description
id	path	yes	string
cycleId	query	no	string	Cycle in this project; defaults to the active or most recent cycle.
language	query	no	string	Narration language: en (default), de, or fr.
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	Sequence	Recorded cycle activity. Missing measurements are null. Test totals count the latest recorded end-to-end journeys, including failed and unverified journeys. Progress counts completed tasks at recorded update times. Graph edges show directory containment and recorded run parentage, rather than inferred dependencies. Narration is cached by workspace, audience, cycle, language and activity window; eviction or restart may regenerate it. Failed narration returns an empty list and is retried after 30 seconds.
400	ApiError	Invalid query
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	Project or cycle not found

Start the project’s autonomous run

POST /v1/api/projects/{id}/start · operation ID startProject

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

Property	Type	Required	Notes
brief	string	yes	min length 1

Responses

Status	Body	Description
200	ProjectStarted	The run was handed to the engine. It starts asynchronously — watch it over the event or stream endpoints.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	A run is already in progress, or the project is archived and cannot accept new work.
502	ApiError	The dispatch could not be queued and the run 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 project’s delivery status

GET /v1/api/projects/{id}/status · operation ID getProjectStatus

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	ProjectStatusSummary	Project status: status (idle, planning, building, checking, ready, paused_budget, stopped or archived), task progress, current cycle, approvals, deployed preview URL and delivery state. Requires view access. A Cloud Machine live preview URL is not included.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Stop every agent working on the project

POST /v1/api/projects/{id}/stop · operation ID stopProject

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	ProjectStopped	The project is stopped. Running agents are told to stop now and nothing new starts; no cycle or task is canceled, so POST /projects/{id}/resume continues where it stopped. Stopping a stopped project answers its current state.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	Nothing is running to stop.

Propose a stack string from the project’s own evidence

POST /v1/api/projects/{id}/suggest-stack · operation ID suggestProjectStack

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	ProjectStackSuggestion	A proposed stack string and its supporting evidence, or stack: null when no stack can be inferred. The proposal is not saved automatically; apply it through PATCH /v1/api/projects/{id}.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	Growth projects run campaigns and have no application stack or Cloud Machine to read or provision.

Open a shell into the project’s Cloud Machine

GET /v1/api/projects/{id}/terminal · operation ID getProjectTerminalAccess

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	ProjectTerminalAccess	A one-use terminal address (webTerminalUrl) that opens one shell on the project’s Cloud Machine, or available: false with a reason. This call starts a Cloud Machine and returns environmentState: "creating" while it starts; poll for availability. environmentState: "absent" means the project has no saved environment and polling alone will not create one. expiresAt is when webTerminalUrl stops working; it opens one shell, once.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).
409	ApiError	Growth projects run campaigns and have no application stack or Cloud Machine to read or provision.

Restore an archived project

POST /v1/api/projects/{id}/unarchive · operation ID unarchiveProject

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	Project	The project was restored to active project lists.
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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Get the project’s cost and token roll-up

GET /v1/api/projects/{id}/usage · operation ID getProjectUsage

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 project in this workspace — or a client collaborator it was never shared with (existence is deliberately not revealed).

Run a command in the project’s Cloud Machine

POST /v1/api/projects/{id}/workspace/exec · operation ID projectWorkspaceExec

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

Property	Type	Required	Notes
command	string	yes	min length 1, max length 100000
cwd	string	no	min length 1, max length 4096
timeoutMs	integer	no	max 1800000

Responses

Status	Body	Description
200	WorkspaceExecResult	The command ran in the project’s Cloud Machine with project secrets available in its environment. A nonzero exitCode is a command result and still returns HTTP 200. cwd defaults to the Coding Workspace root and must remain inside it. Caller-supplied environment variables are not forwarded; write required values through /workspace/fs and source the file.
400	ValidationError | ApiError	cwd escapes the workspace root, or the request named no active organization (ApiError) — or the body failed schema validation, timeoutMs above the thirty-minute ceiling included (ValidationError).
401	ApiError	No valid session or API key.
403	ApiError	Project administration is restricted to the agency.
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 cannot run commands.
503	ApiError	The project’s machine is still starting (code: "workspace_starting", with Retry-After), or it could not be started (code: "workspace_unavailable"; the next call starts a fresh one).

Read or write a file in the project’s Cloud Machine

POST /v1/api/projects/{id}/workspace/fs · operation ID projectWorkspaceFs

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

Property	Type	Required	Notes
content	string	no
dest	string	no	min length 1, max length 4096
encoding	utf8 | base64	no
op	read | write | append | delete | copy | move | mkdir | rmdir | readdir | exists | stat	yes
options	object	no
path	string	yes	min length 1, max length 4096

Responses

Status	Body	Description
200	WorkspaceFsResult	The operation’s answer, shaped by op: read returns { content, encoding }, readdir the directory entries, stat the file’s stat, exists a boolean, and every mutating op null. Paths are workspace-relative (an absolute path must still be inside the workspace root). The call runs in the project’s on-demand machine — started from the project snapshot at the preview branch’s head on first use, deleted 15 minutes after the last call — so a write lives only there until it is committed and pushed.
400	ValidationError | ApiError	The path (or dest) escapes the workspace root, or the request named no active organization (ApiError) — or the body failed schema validation, which includes the op-specific arity: content for a write or append, dest for a copy or move (ValidationError).
401	ApiError	No valid session or API key.
403	ApiError	Project administration is restricted to the agency.
404	ApiError	No such project in this workspace (a client collaborator is never told a project exists) — or the path does not exist inside the workspace.
409	ApiError	The project is archived; or the filesystem refused: the destination already exists, the path is the wrong kind, or a directory is not empty.
500	ApiError	The filesystem operation failed for a reason the contract does not name. error carries the underlying message verbatim, alongside the op and the resolved path it failed on.
503	ApiError	The project’s machine is still starting (code: "workspace_starting", with Retry-After), or it could not be started (code: "workspace_unavailable"; the next call starts a fresh one).

List native project designs

GET /v1/api/projects/{projectId}/designs · operation ID listDesigns

Parameters

Name	In	Required	Type	Description
projectId	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	Design[]	Project designs
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Submit a native prototype brief

POST /v1/api/projects/{projectId}/designs · operation ID createDesign

Parameters

Name	In	Required	Type	Description
projectId	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, CreateDesign (required)

Property	Type	Required	Notes
brief	string	no	min length 1, max length 20000
cycleId	string	no	min length 1
idempotencyKey	string (uuid)	no
intent	design_only | design_and_build	yes
sources	object | object[]	no
title	string	yes	min length 1, max length 200

Responses

Status	Body	Description
201	Design	Design and prototype request created
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Read a design revision and its review threads

GET /v1/api/projects/{projectId}/designs/{designId} · operation ID getDesign

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	path	yes	string
revision	query	no	string	Exact immutable revision; latest when omitted
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	DesignDetail	Design source and review
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Submit implementation of an accepted prototype

POST /v1/api/projects/{projectId}/designs/{designId}/build · operation ID buildDesign

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	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, BuildDesign (required)

Property	Type	Required	Notes
revisionId	string	yes	min length 1

Responses

Status	Body	Description
200	DesignDetail	Implementation request recorded once
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Comment on a frame without dispatching work

POST /v1/api/projects/{projectId}/designs/{designId}/comments · operation ID createDesignComment

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	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, CreateDesignComment (required)

Property	Type	Required	Notes
body	string	yes	min length 1, max length 10000
frameId	string	yes	min length 1, max length 120
parentId	string	no	min length 1
revisionId	string	yes	min length 1
x	number	no	min 0, max 1
y	number	no	min 0, max 1

Responses

Status	Body	Description
201	DesignComment	Revision-anchored 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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Resolve or reopen a design comment

PATCH /v1/api/projects/{projectId}/designs/{designId}/comments/{commentId} · operation ID resolveDesignComment

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	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, ResolveDesignComment (required)

Property	Type	Required	Notes
resolved	boolean	yes

Responses

Status	Body	Description
200	DesignComment	Comment updated
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Accept a revision or submit revision work

POST /v1/api/projects/{projectId}/designs/{designId}/decisions · operation ID decideDesign

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	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, DesignDecision (required)

Property	Type	Required	Notes
comment	string	no	max length 10000
decision	approved | changes_requested	yes
revisionId	string	yes	min length 1

Responses

Status	Body	Description
200	DesignDetail	Revision decision, never production deployment
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Publish a tested playable prototype

POST /v1/api/projects/{projectId}/designs/{designId}/revisions · operation ID publishDesignRevision

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
designId	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, PublishDesignRevision (required)

Property	Type	Required	Notes
context	object	yes
evidence	object[]	yes
expectedRevisionId	string | null	yes
flows	object[]	yes
frames	object[]	yes
html	string	yes	min length 1, max length 2000000
sourcePath	string	no	max length 300

Responses

Status	Body	Description
200	DesignDetail	Immutable revision
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	Design or project not found
409	ApiError	Revision changed or operation conflicts with design scope

Resolve a proposal deep link

GET /v1/api/projects/initial-proposal-by-id/{proposalId} · operation ID resolveProjectInitialProposal

Parameters

Name	In	Required	Type	Description
proposalId	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	InitialProposalDetailResponse	The authorized proposal and its project.
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 proposal in this workspace — or the caller may not see it.

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.