# Runs endpoints

> Runs of a workflow — the central resource: every field value (canonical + formatted) and every task's state in one document. Every operation with parameters, body, responses, errors and examples.

Source: https://developers.processcart.com/reference/runs

Runs of a workflow — the central resource: every field value (canonical + formatted) and every task's state in one document.

Base URL `https://app.processcart.com/api/v1`. Every operation below is also in the [OpenAPI document](https://developers.processcart.com/openapi.json) and the [interactive reference](https://developers.processcart.com/reference).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [List runs](#listRuns) | <code class="pc-docs-wrap">GET /v1<wbr>/runs</code> | Scope `runs:read` |
| [Start a run](#startRun) | <code class="pc-docs-wrap">POST /v1<wbr>/runs</code> | Scope `runs:write` |
| [Get a run](#getRun) | <code class="pc-docs-wrap">GET /v1<wbr>/runs<wbr>/{id}</code> | Scope `runs:read` |
| [Update a run's name, priority, labels, due date or status](#updateRun) | <code class="pc-docs-wrap">PATCH /v1<wbr>/runs<wbr>/{id}</code> | Scope `runs:write` |
| [Move a run to Trash](#trashRun) | <code class="pc-docs-wrap">DELETE /v1<wbr>/runs<wbr>/{id}</code> | Scope `runs:write` |
| [Restore a run from Trash](#restoreRun) | <code class="pc-docs-wrap">POST /v1<wbr>/runs<wbr>/{id}<wbr>/restore</code> | Scope `runs:write` |

## GET /v1/runs
**List runs.** Scope `runs:read` · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated (`{ data, nextCursor, hasMore }`). Operation id `listRuns` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/GET/v1/runs).

Lists the runs the key may see as FULL Run resources (fields and tasks included), newest first. Filter by workflow, status, priority, labels, assignee (`u:<id>` / `g:<id>`), due window or run name; `updatedSince` turns the list into an incremental sync ordered by `updatedAt` ascending (inclusive — overlap by a minute and dedupe by `(id, revision)`). Trashed runs are hidden unless `includeTrashed=true`. `limit` is capped at 100.

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | string (uuid) | no |  |
| `status` | `"active"` \\| `"completed"` \\| `"on_hold"` \\| `"archived"`[] | no | Comma-separated (or repeat the parameter). |
| `priority` | `"none"` \\| `"low"` \\| `"medium"` \\| `"high"` \\| `"urgent"`[] | no | Comma-separated (or repeat the parameter). |
| `labels` | string[] | no | Comma-separated (or repeat the parameter). |
| `assignee` | string | no |  |
| `due` | `"overdue"` \\| `"today"` \\| `"week"` \\| `"none"` | no |  |
| `q` | string | no |  |
| `qMode` | `"prefix"` \\| `"contains"` | no |  |
| `updatedSince` | string (date-time) | no | Incremental sync: only items whose `updatedAt` is at or after this instant (inclusive), ordered by `updatedAt` ascending; an explicit conflicting `sort` / `order` is a 422. Overlap by a minute and dedupe: a Run by `(id, revision)`, any other item (workflow, view, webhook, schedule, automation rule) by `(id, updatedAt)` — a higher `revision` or a later `updatedAt` replaces the copy you hold, an equal one is unchanged. |
| `includeTrashed` | boolean | no |  |
| `sort` | `"startedAt"` \\| `"updatedAt"` \\| `"name"` \\| `"dueAt"` \\| `"keyDate"` \\| `"completedAt"` \\| `"priority"` | no |  |
| `order` | `"asc"` \\| `"desc"` | no |  |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [RunList](https://developers.processcart.com/reference/schemas#runlist) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "8b84a82b-e9d8-4657-aa7c-50452cf48c8d",
      "name": "Order 1001",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 1,
      "updatedAt": "2026-10-13T01:10:36.904Z",
      "startedAt": "2026-10-13T01:10:36.815Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
        "name": "Order fulfillment"
      },
      "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
      "url": "https://app.processcart.com/runs/8b84a82b-e9d8-4657-aa7c-50452cf48c8d",
      "tasks": [
        {
          "key": "details",
          "title": "Details",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "review",
          "title": "Review",
          "kind": "approval",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [
            {
              "kind": "user",
              "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
            }
          ],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "stop",
          "title": "Sign-off",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "wrapup",
          "title": "Wrap up",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": true,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        }
      ],
      "fields": [
        {
          "key": "customer",
          "label": "Customer",
          "type": "text",
          "format": "none",
          "taskKey": "details",
          "value": "Grace Hopper",
          "formatted": "Grace Hopper",
          "visible": true
        },
        {
          "key": "order_code",
          "label": "Order code",
          "type": "text",
          "format": "custom",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "memo",
          "label": "Memo",
          "type": "textarea",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "quantity",
          "label": "Quantity",
          "type": "number",
          "format": "number",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "amount",
          "label": "Amount",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "fee",
          "label": "Fee",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate",
          "label": "Rate",
          "type": "number",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate_text",
          "label": "Rate (text)",
          "type": "text",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "ship_date",
          "label": "Ship date",
          "type": "date",
          "format": "date",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "start_time",
          "label": "Start time",
          "type": "time",
          "format": "time",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "gift_wrap",
          "label": "Gift wrap",
          "type": "dropdown",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "Yes",
            "No"
          ]
        },
        {
          "key": "tags",
          "label": "Tags",
          "type": "multi_choice",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "A",
            "B",
            "C"
          ]
        },
        {
          "key": "agree",
          "label": "Agree",
          "type": "checkbox",
          "format": null,
          "taskKey": "details",
          "value": false,
          "formatted": "No",
          "visible": true
        },
        {
          "key": "contact_email",
          "label": "Contact email",
          "type": "email",
          "format": "email",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "website",
          "label": "Website",
          "type": "url",
          "format": "url",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "phone",
          "label": "Phone",
          "type": "phone",
          "format": "phone",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "owner",
          "label": "Owner",
          "type": "members",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "steps",
          "label": "Steps",
          "type": "subtasks",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "items": [
            {
              "key": "photos",
              "label": "Photos"
            },
            {
              "key": "invoice",
              "label": "Invoice"
            }
          ]
        },
        {
          "key": "contract",
          "label": "Contract",
          "type": "file",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "double_amount",
          "label": "Double amount",
          "type": "formula",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    },
    {
      "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
      "name": "Order 1002",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 7,
      "updatedAt": "2026-10-13T01:10:35.496Z",
      "startedAt": "2026-10-13T01:10:02.387Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
        "name": "Order fulfillment"
      },
      "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
      "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
      "tasks": [
        {
          "key": "details",
          "title": "Details",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "review",
          "title": "Review",
          "kind": "approval",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [
            {
              "kind": "user",
              "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
            }
          ],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "stop",
          "title": "Sign-off",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "wrapup",
          "title": "Wrap up",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": true,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        }
      ],
      "fields": [
        {
          "key": "customer",
          "label": "Customer",
          "type": "text",
          "format": "none",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "order_code",
          "label": "Order code",
          "type": "text",
          "format": "custom",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "memo",
          "label": "Memo",
          "type": "textarea",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "quantity",
          "label": "Quantity",
          "type": "number",
          "format": "number",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "amount",
          "label": "Amount",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "fee",
          "label": "Fee",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate",
          "label": "Rate",
          "type": "number",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate_text",
          "label": "Rate (text)",
          "type": "text",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "ship_date",
          "label": "Ship date",
          "type": "date",
          "format": "date",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "start_time",
          "label": "Start time",
          "type": "time",
          "format": "time",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "gift_wrap",
          "label": "Gift wrap",
          "type": "dropdown",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "Yes",
            "No"
          ]
        },
        {
          "key": "tags",
          "label": "Tags",
          "type": "multi_choice",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "A",
            "B",
            "C"
          ]
        },
        {
          "key": "agree",
          "label": "Agree",
          "type": "checkbox",
          "format": null,
          "taskKey": "details",
          "value": false,
          "formatted": "No",
          "visible": true
        },
        {
          "key": "contact_email",
          "label": "Contact email",
          "type": "email",
          "format": "email",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "website",
          "label": "Website",
          "type": "url",
          "format": "url",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "phone",
          "label": "Phone",
          "type": "phone",
          "format": "phone",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "owner",
          "label": "Owner",
          "type": "members",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "steps",
          "label": "Steps",
          "type": "subtasks",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "items": [
            {
              "key": "photos",
              "label": "Photos"
            },
            {
              "key": "invoice",
              "label": "Invoice"
            }
          ]
        },
        {
          "key": "contract",
          "label": "Contract",
          "type": "file",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "double_amount",
          "label": "Double amount",
          "type": "formula",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    }
  ],
  "nextCursor": "eyJ2IjoiMjAyNi0xMC0xM1QwMToxMDowMi4zODcwMDBaIiwiaWQiOiI4NDVkNDc0NS00Y2MxLTQ2ZmUtOWQ2Yy0zY2ZlYWQ3NDU0NGYiLCJoIjoiYjU0MzliODk0MmUxZDhlNiJ9",
  "hasMore": true
}
```


## POST /v1/runs
**Start a run.** Scope `runs:write` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key`. Operation id `startRun` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/POST/v1/runs).

Starts a run of a workflow's published version with a name, optional field values (any writable field; kickoff fields marked required must be present), priority, labels and due date — in one transaction. A visible kickoff field (required or not) whose value breaks its bounds or rules is refused with 422 `validation_failed` (`errors[].code` `invalid_value`), the same gate as the app's Start dialog; other fields are accepted and flagged in `validationError`, as on `PATCH /runs/{id}/fields`. Returns the new Run (`revision: 1`) and an absolute `Location` header.

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |

**Request body** — `application/json`, [RunStart](https://developers.processcart.com/reference/schemas#runstart)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | [Uuid](https://developers.processcart.com/reference/schemas#uuid) | yes |  |
| `name` | string | yes |  |
| `fields` | [FieldsWrite](https://developers.processcart.com/reference/schemas#fieldswrite) | no |  |
| `priority` | [RunPriority](https://developers.processcart.com/reference/schemas#runpriority) | no |  |
| `labels` | string[] | no |  |
| `dueAt` | [Instant](https://developers.processcart.com/reference/schemas#instant) \\| [CalendarDate](https://developers.processcart.com/reference/schemas#calendardate) \\| null | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 201 | Created. `Location` names the new resource. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `field_not_writable` — Field is not writable; `idempotency_key_reused` — Idempotency key reused; `required_fields_unsatisfied` — Required fields unsatisfied; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`workflow_not_published`](https://developers.processcart.com/errors#workflow_not_published) — Workflow not published
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`field_not_writable`](https://developers.processcart.com/errors#field_not_writable) — Field is not writable
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`required_fields_unsatisfied`](https://developers.processcart.com/errors#required_fields_unsatisfied) — Required fields unsatisfied
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "workflowId": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
  "name": "ORD 2026-10-15 Acme Corp",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "dueAt": "2026-10-20",
  "fields": {
    "customer": "Ada Lovelace",
    "amount": "$1,700.00",
    "rate": "5%",
    "rate_text": 0.05,
    "quantity": 1250,
    "fee": 900,
    "ship_date": "2026-10-15",
    "start_time": "14:30",
    "gift_wrap": "Yes",
    "tags": [
      "A",
      "C"
    ],
    "agree": true,
    "contact_email": "Ada@Example.com",
    "website": "example.com",
    "phone": "(415) 555-0100",
    "owner": [
      "e9e90546-8500-4502-a8a3-0f705c013cfd"
    ],
    "steps": [
      "photos"
    ],
    "source": "zapier",
    "order_code": "AB-1234",
    "memo": "Two lines\nhere"
  }
}
```

**Example response** (201)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "status": "active",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "labelDetails": [
    {
      "id": "rush",
      "name": "Rush",
      "color": "#dc2626"
    }
  ],
  "dueAt": "2026-10-21T06:59:59.000Z",
  "keyDate": "2026-10-15",
  "revision": 1,
  "updatedAt": "2026-10-13T01:09:29.022Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}
```


## GET /v1/runs/{id}
**Get a run.** Scope `runs:read` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it). Operation id `getRun` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/GET/v1/runs/{id}).

Returns one run with every field value (canonical + formatted) and task state, plus its `revision` — send it back as `Expected-Revision` on a write that must not overwrite a newer change. A run in Trash loads with `deletedAt` set.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "status": "active",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "labelDetails": [
    {
      "id": "rush",
      "name": "Rush",
      "color": "#dc2626"
    }
  ],
  "dueAt": "2026-10-21T06:59:59.000Z",
  "keyDate": "2026-10-15",
  "revision": 1,
  "updatedAt": "2026-10-13T01:09:29.022Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}
```


## PATCH /v1/runs/{id}
**Update a run's name, priority, labels, due date or status.** Scope `runs:write` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key` · accepts `Expected-Revision` (409 `revision_mismatch` when stale). Operation id `updateRun` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/PATCH/v1/runs/{id}).

Changes run-level attributes under the run lock. `status` is applied first; an archived run refuses every other change. Label ids are checked against the org's label set. Send `Expected-Revision` to refuse the write when the run changed since you read it.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |
| `Expected-Revision` | string | no | Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412. |

**Request body** — `application/json`, [RunPatch](https://developers.processcart.com/reference/schemas#runpatch)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `priority` | [RunPriority](https://developers.processcart.com/reference/schemas#runpriority) | no |  |
| `labels` | string[] | no |  |
| `dueAt` | [Instant](https://developers.processcart.com/reference/schemas#instant) \\| [CalendarDate](https://developers.processcart.com/reference/schemas#calendardate) \\| null | no |  |
| `status` | [RunStatus](https://developers.processcart.com/reference/schemas#runstatus) | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `run_archived` — Run is archived; `run_trashed` — Run is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`revision_mismatch`](https://developers.processcart.com/errors#revision_mismatch) — Revision mismatch
- 409 [`run_archived`](https://developers.processcart.com/errors#run_archived) — Run is archived
- 409 [`run_trashed`](https://developers.processcart.com/errors#run_trashed) — Run is in Trash
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "ORD 2026-10-15 Acme Corp (renamed)",
  "priority": "high",
  "labels": [
    "waiting"
  ],
  "dueAt": "2026-11-01T17:00:00Z"
}
```

**Example response** (200)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp (renamed)",
  "status": "active",
  "priority": "high",
  "labels": [
    "waiting"
  ],
  "labelDetails": [
    {
      "id": "waiting",
      "name": "Waiting",
      "color": "#f59e0b"
    }
  ],
  "dueAt": "2026-11-01T17:00:00.000Z",
  "keyDate": "2026-10-15",
  "revision": 2,
  "updatedAt": "2026-10-13T01:09:37.189Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}
```


## DELETE /v1/runs/{id}
**Move a run to Trash.** Scope `runs:write` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key` · accepts `Expected-Revision` (409 `revision_mismatch` when stale). Operation id `trashRun` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/DELETE/v1/runs/{id}).

Soft-deletes the run (recoverable from Trash for 30 days). Returns the Run with `deletedAt` set; a run already in Trash answers 200 unchanged.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |
| `Expected-Revision` | string | no | Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`revision_mismatch`](https://developers.processcart.com/errors#revision_mismatch) — Revision mismatch
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "name": "Order 1002",
  "status": "active",
  "priority": "none",
  "labels": [],
  "labelDetails": [],
  "dueAt": null,
  "keyDate": null,
  "revision": 4,
  "updatedAt": "2026-10-13T01:10:28.661Z",
  "startedAt": "2026-10-13T01:10:02.387Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": "2026-10-13T01:10:28.586Z",
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": false
    }
  ]
}
```


## POST /v1/runs/{id}/restore
**Restore a run from Trash.** Scope `runs:write` · checked against the key's workflow / folder allowlist (403 `not_allowed_for_key` outside it) · accepts `Idempotency-Key` · accepts `Expected-Revision` (409 `revision_mismatch` when stale). Operation id `restoreRun` · [open in the API reference](https://developers.processcart.com/reference#tag/runs/POST/v1/runs/{id}/restore).

Brings a trashed run back. A run that is not in Trash answers 200 unchanged; a run whose workflow is itself in Trash is refused (restore the workflow first). `Expected-Revision` is honored as a compare-and-set.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

**Request headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored. |
| `Expected-Revision` | string | no | Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [Run](https://developers.processcart.com/reference/schemas#run) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `workflow_trashed` — Workflow is in Trash. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 409 [`revision_mismatch`](https://developers.processcart.com/errors#revision_mismatch) — Revision mismatch
- 409 [`workflow_trashed`](https://developers.processcart.com/errors#workflow_trashed) — Workflow is in Trash
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "name": "Order 1002",
  "status": "active",
  "priority": "none",
  "labels": [],
  "labelDetails": [],
  "dueAt": null,
  "keyDate": null,
  "revision": 5,
  "updatedAt": "2026-10-13T01:10:33.053Z",
  "startedAt": "2026-10-13T01:10:02.387Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": false
    }
  ]
}
```