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.

View this page as Markdown

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 and the interactive reference.

Operation	Method and path	Scope
List a run's tasks	`GET /v1/runs/{id}/tasks`	Scope `runs:read`
Complete a task	`POST /v1/runs/{id}/tasks/{key}/complete`	Scope `runs:write`
Reopen a completed task	`POST /v1/runs/{id}/tasks/{key}/reopen`	Scope `runs:write`
Approve an approval task	`POST /v1/runs/{id}/tasks/{key}/approve`	Scope `approvals:decide`
Reject an approval task	`POST /v1/runs/{id}/tasks/{key}/reject`	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.

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
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
422	`validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
404 not_found — Not found
405 method_not_allowed — Method not allowed
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "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.

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
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
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
422	`idempotency_key_reused` — Idempotency key reused; `required_fields_unsatisfied` — Required fields unsatisfied; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
409 task_hidden — Task is hidden
409 task_locked — Task is locked
409 task_not_configured — Task not configured
409 wrong_task_kind — Wrong task kind
422 idempotency_key_reused — Idempotency key reused
422 required_fields_unsatisfied — Required fields unsatisfied
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "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.

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
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
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
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `run_archived` — Run is archived; `run_trashed` — Run is in Trash.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 approver_only — Approver only
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "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.

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

Property	Type	Required	Description
`comment`	string	no

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
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
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
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
413	`payload_too_large` — Payload too large.	Problem
415	`unsupported_media_type` — Unsupported media type.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `required_fields_unsatisfied` — Required fields unsatisfied; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 approver_only — Approver only
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
409 task_completed — Task already completed
409 task_hidden — Task is hidden
409 task_locked — Task is locked
409 wrong_task_kind — Wrong task kind
413 payload_too_large — Payload too large
415 unsupported_media_type — Unsupported media type
422 idempotency_key_reused — Idempotency key reused
422 required_fields_unsatisfied — Required fields unsatisfied
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example request

{
  "comment": "Looks good."
}

Example response (200)

{
  "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.

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

Property	Type	Required	Description
`comment`	string	no

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
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
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
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
413	`payload_too_large` — Payload too large.	Problem
415	`unsupported_media_type` — Unsupported media type.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 approver_only — Approver only
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
409 task_completed — Task already completed
409 task_hidden — Task is hidden
409 task_locked — Task is locked
409 wrong_task_kind — Wrong task kind
413 payload_too_large — Payload too large
415 unsupported_media_type — Unsupported media type
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example request

{
  "comment": "Redo the photos before I sign."
}

Example response (200)

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