Workflows API

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

string

required

Display name for the workflow.

string

Optional description of the workflow’s purpose.

object[]

required

Array of status definitions. Each status has a key, label, and optional isTerminal flag.

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

string

required

Display name for the field.

string

required

Unique key for the field within this workflow. Used as the identifier when setting field values on work items.

string

required

Field type: text, number, boolean, date, or select.

boolean

Whether the field must be set before a work item can transition to certain statuses.

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"]
  }'

{
  "id": "field_abc789",
  "workflowId": "wf_xyz456",
  "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

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.

Overview

Work Items

Integrations

Workflows

List workflows

Create a workflow

Get a workflow

Update a workflow

Delete a workflow

Custom fields

List custom fields

Create a custom field

Update a custom field

Delete a custom field

Domain workflow assignment

List workflows for a domain

Attach a workflow to a domain

​Workflows

​List workflows

​Create a workflow

​Get a workflow

​Update a workflow

​Delete a workflow

​Custom fields

​List custom fields

​Create a custom field

​Update a custom field

​Delete a custom field

​Domain workflow assignment

​List workflows for a domain

​Attach a workflow to a domain

Workflows

List workflows

Create a workflow

Get a workflow

Update a workflow

Delete a workflow

Custom fields

List custom fields

Create a custom field

Update a custom field

Delete a custom field

Domain workflow assignment

List workflows for a domain

Attach a workflow to a domain