Skip to main content
Workflows control the lifecycle of work items in a domain. A workflow defines the valid statuses a work item can move through, the stages that group those statuses, the stage gates that enforce requirements at transitions, and the custom fields that capture structured data during execution.

Statuses

Named states a work item can be in, such as backlog, in_progress, or completed.

Stages

Groups of statuses that represent a phase of work. Stage gates enforce entry requirements.

Stage gates

Checkpoints between stages that require acknowledgement, checklist completion, or custom-field values before progressing.

Custom fields

Structured data fields attached to a workflow, optionally required at specific transitions.

​
Creating a workflow

Use the API to create a workflow in your domain:
Workflows can be personal-domain or domain-scoped. Once a work item references a workflowId, that value is immutable.

​
Managing workflow statuses and stages

After creating a workflow, update its statuses and stages:
Status transitions, stage membership, and stage gate configurations are all managed through this endpoint.
All status transitions and stage gate requirements are validated server-side. A work item cannot bypass a gate through the API or CLI.

​
Adding custom fields

Custom fields let you capture structured data on work items that use a workflow. Add a field with:
You can also update or delete fields:
Field types available on work items include text, number, select, and date values. Fields can be marked as required at specific stage transitions — the server enforces these requirements when an agent or user attempts to progress the work item.

​
Attaching a workflow to a domain

Once a workflow is configured, attach it to a domain so it becomes available when creating work items in that domain:
To see all workflows available in a domain:

​
Viewing workflows via CLI

​
Assigning a workflow to a work item

Pass --workflow-id when creating or updating a work item:

​
Viewing available transitions

Before claiming or progressing a work item, check which status transitions and stage gates are currently available:
The output includes:
  • availableTransitions: statuses reachable from the current state
  • availableStageGates: gates that can be progressed right now
  • terminalStatuses: statuses that mark the work item as resolved

​
Progressing through a stage gate

When a workflow stage has a gate, you must satisfy its requirements before moving to the next stage.
1

Check available gates

The response shows available stage gates and their keys.
2

Progress through a text-acknowledgement gate

3

Progress through a checklist gate

Pass every required checklist item. The server rejects the request if any required item is missing.
Use --to-stage to resolve the gate from the current availableStageGates automatically. Use --stage-gate-key when you want to target a specific gate explicitly.

​
Completing work

Once a work item has progressed through its workflow, claim it, complete it, or use the one-shot done shortcut:
complete requires a terminal status from the workflow’s terminalStatuses list. It clears active agent fields and marks the work item as resolved.