> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API

> Manage workflow definitions and custom fields via the OpenIndex 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](/api/authentication).

## Workflows

### List workflows

```bash theme={null}
GET /workflows
Authorization: Bearer <your-pat>
```

Returns all workflows accessible to the authenticated user, including personal and domain-scoped workflows.

### Create a workflow

```bash theme={null}
POST /workflows
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.name" type="string" required>
  Display name for the workflow.
</ParamField>

<ParamField path="body.description" type="string">
  Optional description of the workflow's purpose.
</ParamField>

<ParamField path="body.statuses" type="object[]" required>
  Array of status definitions. Each status has a `key`, `label`, and optional `isTerminal` flag.
</ParamField>

<ParamField path="body.stages" type="object[]">
  Array of stage definitions, each specifying stage gates and whether the stage requires an agent.
</ParamField>

### Get a workflow

```bash theme={null}
GET /workflows/:id
Authorization: Bearer <your-pat>
```

### Update a workflow

```bash theme={null}
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

```bash theme={null}
DELETE /workflows/:id
Authorization: Bearer <your-pat>
```

<Warning>
  You cannot delete a workflow that is currently referenced by work items. Reassign those items to a different workflow first.
</Warning>

## Custom fields

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

### List custom fields

```bash theme={null}
GET /workflows/:id/fields
Authorization: Bearer <your-pat>
```

### Create a custom field

```bash theme={null}
POST /workflows/:id/fields
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.name" type="string" required>
  Display name for the field.
</ParamField>

<ParamField path="body.key" type="string" required>
  Unique key for the field within this workflow. Used as the identifier when setting field values on work items.
</ParamField>

<ParamField path="body.type" type="string" required>
  Field type: `text`, `number`, `boolean`, `date`, or `select`.
</ParamField>

<ParamField path="body.required" type="boolean">
  Whether the field must be set before a work item can transition to certain statuses.
</ParamField>

<ParamField path="body.options" type="string[]">
  For `select` type fields: the allowed option values.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "field_abc789",
    "workflowId": "wf_xyz456",
    "name": "Environment",
    "key": "environment",
    "type": "select",
    "required": true,
    "options": ["development", "staging", "production"]
  }
  ```
</CodeGroup>

### Update a custom field

```bash theme={null}
PATCH /workflows/:id/fields/:fieldId
Authorization: Bearer <your-pat>
Content-Type: application/json
```

### Delete a custom field

```bash theme={null}
DELETE /workflows/:id/fields/:fieldId
Authorization: Bearer <your-pat>
```

<Note>
  Deleting a custom field removes it from all work items using the workflow. Existing field values are permanently discarded.
</Note>

## Domain workflow assignment

### List workflows for a domain

```bash theme={null}
GET /domains/:id/workflows
Authorization: Bearer <your-pat>
```

Returns all workflows attached to the given domain.

### Attach a workflow to a domain

```bash theme={null}
POST /domains/:id/workflows
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.workflowId" type="string" required>
  ID of the workflow to attach to the domain.
</ParamField>

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.