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: 
POST /workflows

{
  "name": "Triage",
  "description": "Default triage workflow for incoming requests",
  "domain": "<domain-id>"
}
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: 
PATCH /workflows/:id
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: 
POST /workflows/:id/fields
You can also update or delete fields: 
PATCH /workflows/:id/fields/:fieldId
DELETE /workflows/:id/fields/:fieldId
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: 
POST /domains/:id/workflows
To see all workflows available in a domain: 
GET /domains/:id/workflows

​
Viewing workflows via CLI

# List all workflows in a domain
oi settings domain workflows list --domain OPS

# Get a specific workflow
oi settings domain workflows get TRIAGE --domain OPS

# List custom fields on a workflow
oi settings domain workflows fields list TRIAGE --domain OPS

​
Assigning a workflow to a work item

Pass --workflow-id when creating or updating a work item: 
oi work-item create --kind task --title "Review request" --domain-id <id> --workflow-id <workflow-id>

oi work-item update ABC-123 --workflow-id <workflow-id>

​
Viewing available transitions

Before claiming or progressing a work item, check which status transitions and stage gates are currently available: 
oi work-item transitions ABC-123
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

oi work-item transitions ABC-123
The response shows available stage gates and their keys.
2

Progress through a text-acknowledgement gate

oi work-item progress ABC-123 --to-stage waiting_for_input --accept-requirements-text
3

Progress through a checklist gate

oi work-item progress ABC-123 --stage-gate-key <gate-key> \
  --checked-requirement-item "First requirement" \
  --checked-requirement-item "Second requirement"
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: 
# Claim the item (mark as in-progress)
oi work-item claim ABC-123 --to-status in_progress

# Complete the item (resolve and clear agent fields)
oi work-item complete ABC-123 --to-status completed

# One-shot: auto-progress through all valid stage gates to completion
oi work-item done ABC-123
complete requires a terminal status from the workflow’s terminalStatuses list. It clears active agent fields and marks the work item as resolved.