# Tasks endpoints

> Complete, reopen, approve and reject a run's tasks under the engine's gates. Every operation with parameters, body, responses, errors and examples.

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

Complete, reopen, approve and reject a run's tasks under the engine's gates.

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 a run's tasks](#listRunTasks) | <code class="pc-docs-wrap">GET /v1<wbr>/runs<wbr>/{id}<wbr>/tasks</code> | Scope `runs:read` |
| [Complete a task](#completeTask) | <code class="pc-docs-wrap">POST /v1<wbr>/runs<wbr>/{id}<wbr>/tasks<wbr>/{key}<wbr>/complete</code> | Scope `runs:write` |
| [Reopen a completed task](#reopenTask) | <code class="pc-docs-wrap">POST /v1<wbr>/runs<wbr>/{id}<wbr>/tasks<wbr>/{key}<wbr>/reopen</code> | Scope `runs:write` |
| [Approve an approval task](#approveTask) | <code class="pc-docs-wrap">POST /v1<wbr>/runs<wbr>/{id}<wbr>/tasks<wbr>/{key}<wbr>/approve</code> | Scope `approvals:decide` |
| [Reject an approval task](#rejectTask) | <code class="pc-docs-wrap">POST /v1<wbr>/runs<wbr>/{id}<wbr>/tasks<wbr>/{key}<wbr>/reject</code> | Scope `approvals:decide` |

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

The run's tasks in checklist order with state, visibility, lock, due date and assignees — the same `tasks[]` the Run carries, as a bounded list (`nextCursor` is null). It takes no query parameters (an unknown one is a 422).

**Path parameters**

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

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [RunTaskList](https://developers.processcart.com/reference/schemas#runtasklist) |
| 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
{
  "data": [
    {
      "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
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```


## POST /v1/runs/{id}/tasks/{key}/complete
**Complete a task.** 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 `completeTask` · [open in the API reference](https://developers.processcart.com/reference#tag/tasks/POST/v1/runs/{id}/tasks/{key}/complete).

Marks a standard task done, after the engine's gates: the task must be visible and unlocked and its required fields satisfied (every offender is listed in `errors[]`). Approval tasks are decided through approve / reject instead; an already-completed task answers 200 unchanged.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `key` | string | 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; `run_archived` — Run is archived; `run_trashed` — Run is in Trash; `task_hidden` — Task is hidden; `task_locked` — Task is locked; `task_not_configured` — Task not configured; `wrong_task_kind` — Wrong task kind. | [Problem](https://developers.processcart.com/errors) |
| 422 | `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 [`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
- 409 [`task_hidden`](https://developers.processcart.com/errors#task_hidden) — Task is hidden
- 409 [`task_locked`](https://developers.processcart.com/errors#task_locked) — Task is locked
- 409 [`task_not_configured`](https://developers.processcart.com/errors#task_not_configured) — Task not configured
- 409 [`wrong_task_kind`](https://developers.processcart.com/errors#wrong_task_kind) — Wrong task kind
- 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 response** (200)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "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": 9,
  "updatedAt": "2026-10-13T01:09:58.990Z",
  "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": "done",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": "2026-10-13T01:09:58.900Z",
      "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": "Updated by the API",
      "formatted": "Updated by the API",
      "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": 1850,
      "formatted": "$1,850.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 400,
      "formatted": "$400.00",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.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": 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": "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": [
        "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
      ],
      "formatted": "Fixture Member",
      "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": 3700,
      "formatted": "$3,700.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": 42,
      "formatted": "42",
      "visible": false
    }
  ]
}
```


## POST /v1/runs/{id}/tasks/{key}/reopen
**Reopen a completed task.** 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 `reopenTask` · [open in the API reference](https://developers.processcart.com/reference#tag/tasks/POST/v1/runs/{id}/tasks/{key}/reopen).

Puts a done task back to to-do (a completed run becomes active again). Reopening an approval needs the `approvals:decide` scope. A task that is not done answers 200 unchanged. A hidden or locked task can still be reopened — only complete, approve and reject gate on visibility and locks.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `key` | string | 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 | `approver_only` — Approver only; `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) |
| 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 [`approver_only`](https://developers.processcart.com/errors#approver_only) — Approver only
- 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
- 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": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "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": 13,
  "updatedAt": "2026-10-13T01:10:15.207Z",
  "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": "done",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": "2026-10-13T01:10:10.107Z",
      "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": "Updated by the API",
      "formatted": "Updated by the API",
      "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": 1850,
      "formatted": "$1,850.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 400,
      "formatted": "$400.00",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.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": 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": "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": [
        "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
      ],
      "formatted": "Fixture Member",
      "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": 3700,
      "formatted": "$3,700.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": 42,
      "formatted": "42",
      "visible": false
    }
  ]
}
```


## POST /v1/runs/{id}/tasks/{key}/approve
**Approve an approval task.** Scope `approvals:decide` · 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 `approveTask` · [open in the API reference](https://developers.processcart.com/reference#tag/tasks/POST/v1/runs/{id}/tasks/{key}/approve).

Records an approval with an optional comment; the body may be left out, or sent as `{}`, when there is nothing to add. Needs the `approvals:decide` scope — the key then decides with Admin authority. An approval already approved is refused until it is reopened.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `key` | string | 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`, [TaskDecision](https://developers.processcart.com/reference/schemas#taskdecision)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | string | 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 | `approver_only` — Approver only; `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; `task_completed` — Task already completed; `task_hidden` — Task is hidden; `task_locked` — Task is locked; `wrong_task_kind` — Wrong task kind. | [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; `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 [`approver_only`](https://developers.processcart.com/errors#approver_only) — Approver only
- 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
- 409 [`task_completed`](https://developers.processcart.com/errors#task_completed) — Task already completed
- 409 [`task_hidden`](https://developers.processcart.com/errors#task_hidden) — Task is hidden
- 409 [`task_locked`](https://developers.processcart.com/errors#task_locked) — Task is locked
- 409 [`wrong_task_kind`](https://developers.processcart.com/errors#wrong_task_kind) — Wrong task kind
- 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 [`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
{
  "comment": "Looks good."
}
```

**Example response** (200)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "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": 14,
  "updatedAt": "2026-10-13T01:10:17.100Z",
  "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": "done",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": "2026-10-13T01:10:10.107Z",
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "done",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": "2026-10-13T01:10:17.009Z",
      "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": "Updated by the API",
      "formatted": "Updated by the API",
      "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": 1850,
      "formatted": "$1,850.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 400,
      "formatted": "$400.00",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.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": 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": "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": [
        "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
      ],
      "formatted": "Fixture Member",
      "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": 3700,
      "formatted": "$3,700.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": 42,
      "formatted": "42",
      "visible": false
    }
  ]
}
```


## POST /v1/runs/{id}/tasks/{key}/reject
**Reject an approval task.** Scope `approvals:decide` · 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 `rejectTask` · [open in the API reference](https://developers.processcart.com/reference#tag/tasks/POST/v1/runs/{id}/tasks/{key}/reject).

Records a rejection — the comment is required — and sends the configured earlier tasks back for redo. Needs the `approvals:decide` scope. A duplicate rejection answers 200 unchanged. An approval already approved is refused until it is reopened.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `key` | string | 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`, [TaskDecision](https://developers.processcart.com/reference/schemas#taskdecision)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | string | 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 | `approver_only` — Approver only; `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; `task_completed` — Task already completed; `task_hidden` — Task is hidden; `task_locked` — Task is locked; `wrong_task_kind` — Wrong task kind. | [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 [`approver_only`](https://developers.processcart.com/errors#approver_only) — Approver only
- 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
- 409 [`task_completed`](https://developers.processcart.com/errors#task_completed) — Task already completed
- 409 [`task_hidden`](https://developers.processcart.com/errors#task_hidden) — Task is hidden
- 409 [`task_locked`](https://developers.processcart.com/errors#task_locked) — Task is locked
- 409 [`wrong_task_kind`](https://developers.processcart.com/errors#wrong_task_kind) — Wrong task kind
- 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
{
  "comment": "Redo the photos before I sign."
}
```

**Example response** (200)

```json
{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "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": 10,
  "updatedAt": "2026-10-13T01:10:07.652Z",
  "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": "rejected_redo",
      "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": "Updated by the API",
      "formatted": "Updated by the API",
      "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": 1850,
      "formatted": "$1,850.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 400,
      "formatted": "$400.00",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.075,
      "formatted": "7.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": 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": "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": [
        "61465009-1ab5-4eb6-b4f3-3aae0718d1fb"
      ],
      "formatted": "Fixture Member",
      "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": 3700,
      "formatted": "$3,700.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": 42,
      "formatted": "42",
      "visible": false
    }
  ]
}
```