Skip to main content
Workflows define the status transitions, stage gates, and custom fields that govern how work items move through your process. Workflows can be personal (owned by your user) or domain-scoped (shared across a domain). All workflow endpoints require a Bearer token. See API Authentication.

​
Workflows

​
List workflows

GET /workflows
Authorization: Bearer <your-pat>
Returns all workflows accessible to the authenticated user, including personal and domain-scoped workflows.

​
Create a workflow

POST /workflows
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.name
string
required
Display name for the workflow.
​
body.description
string
Optional description of the workflow’s purpose.
​
body.statuses
object[]
required
Array of status definitions. Each status has a key, label, and optional isTerminal flag.
​
body.stages
object[]
Array of stage definitions, each specifying stage gates and whether the stage requires an agent.

​
Get a workflow

GET /workflows/:id
Authorization: Bearer <your-pat>

​
Update a workflow

PATCH /workflows/:id
Authorization: Bearer <your-pat>
Content-Type: application/json
Send only the fields you want to update. You can add or update statuses and stages, but removing statuses that are in use by work items is blocked server-side.

​
Delete a workflow

DELETE /workflows/:id
Authorization: Bearer <your-pat>
You cannot delete a workflow that is currently referenced by work items. Reassign those items to a different workflow first.

​
Custom fields

Custom fields are attached to a workflow and apply to all work items using that workflow.

​
List custom fields

GET /workflows/:id/fields
Authorization: Bearer <your-pat>

​
Create a custom field

POST /workflows/:id/fields
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.name
string
required
Display name for the field.
​
body.key
string
required
Unique key for the field within this workflow. Used as the identifier when setting field values on work items.
​
body.type
string
required
Field type: text, number, boolean, date, or select.
​
body.required
boolean
Whether the field must be set before a work item can transition to certain statuses.
​
body.options
string[]
For select type fields: the allowed option values.
curl --request POST \
  --url https://your-deployment.convex.site/workflows/wf_xyz456/fields \
  --header 'Authorization: Bearer oi_pat_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Environment",
    "key": "environment",
    "type": "select",
    "required": true,
    "options": ["development", "staging", "production"]
  }'

​
Update a custom field

PATCH /workflows/:id/fields/:fieldId
Authorization: Bearer <your-pat>
Content-Type: application/json

​
Delete a custom field

DELETE /workflows/:id/fields/:fieldId
Authorization: Bearer <your-pat>
Deleting a custom field removes it from all work items using the workflow. Existing field values are permanently discarded.

​
Domain workflow assignment

​
List workflows for a domain

GET /domains/:id/workflows
Authorization: Bearer <your-pat>
Returns all workflows attached to the given domain.

​
Attach a workflow to a domain

POST /domains/:id/workflows
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.workflowId
string
required
ID of the workflow to attach to the domain.
Attaching a workflow to a domain makes it available when creating work items in that domain. The first workflow attached to a domain becomes the default for new work items.