Comments endpoints

Task comments on a run. Every operation with parameters, body, responses, errors and examples.

Task comments on a run.

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 comments	`GET /v1/runs/{id}/comments`	Scope `runs:read`
Comment on a task	`POST /v1/runs/{id}/comments`	Scope `runs:write`
Get a comment	`GET /v1/runs/{id}/comments/{commentId}`	Scope `runs:read`

GET /v1/runs/{id}/comments

List a run's comments. Scope runs:read · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · paginated ({ data, nextCursor, hasMore }). Operation id listRunComments · open in the API reference.

The run's live comments, oldest first, with the author, the sanitized body, a plain-text rendering and the mentioned member ids. A run in Trash still answers.

Path parameters

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

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

Name	Type	Required	Description
`limit`	integer	no
`cursor`	string	no	The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422.

Responses

Status	Meaning	Body
200	OK.	ListRunCommentsResponse
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": [
    {
      "id": "32629d31-996c-48af-8637-261a6aea7eca",
      "runId": "3245e6a5-3fbe-463a-ad0b-a7fd871957b0",
      "taskKey": "details",
      "runTaskId": "7d6b86f6-5f67-4729-870c-ed29c1be3009",
      "author": {
        "kind": "api",
        "keyId": "d422b49f-a3f2-4244-b97e-8d50f25c3036",
        "name": "collab key"
      },
      "body": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "text": "Hello from the API",
                "type": "text"
              },
              {
                "type": "hardBreak"
              },
              {
                "text": "second line",
                "type": "text"
              }
            ]
          }
        ]
      },
      "text": "Hello from the API\nsecond line",
      "mentions": [],
      "createdAt": "2026-10-13T01:09:30.295Z",
      "editedAt": null,
      "url": "https://app.processcart.com/runs/3245e6a5-3fbe-463a-ad0b-a7fd871957b0?task=details"
    },
    {
      "id": "65c213cd-053b-47aa-93ec-c7fd21b06a49",
      "runId": "3245e6a5-3fbe-463a-ad0b-a7fd871957b0",
      "taskKey": "details",
      "runTaskId": "7d6b86f6-5f67-4729-870c-ed29c1be3009",
      "author": {
        "kind": "api",
        "keyId": "d422b49f-a3f2-4244-b97e-8d50f25c3036",
        "name": "collab key"
      },
      "body": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "text": "Ping ",
                "type": "text"
              },
              {
                "type": "mention",
                "attrs": {
                  "id": "0515df8b-d0b5-43c5-b535-3b87ec2df4a8",
                  "label": "Fixture Member"
                }
              },
              {
                "text": " and ",
                "type": "text"
              },
              {
                "text": " cc ",
                "type": "text"
              },
              {
                "type": "mention",
                "attrs": {
                  "id": "f3e7a668-7e78-44f2-bc92-4457a9a54337",
                  "label": "Fixture Admin"
                }
              }
            ]
          }
        ]
      },
      "text": "Ping @Fixture Member and  cc @Fixture Admin",
      "mentions": [
        "0515df8b-d0b5-43c5-b535-3b87ec2df4a8",
        "f3e7a668-7e78-44f2-bc92-4457a9a54337"
      ],
      "createdAt": "2026-10-13T01:09:32.773Z",
      "editedAt": null,
      "url": "https://app.processcart.com/runs/3245e6a5-3fbe-463a-ad0b-a7fd871957b0?task=details"
    },
    {
      "id": "b70b33e8-8a42-4289-8fa7-564929b05c43",
      "runId": "3245e6a5-3fbe-463a-ad0b-a7fd871957b0",
      "taskKey": "details",
      "runTaskId": "7d6b86f6-5f67-4729-870c-ed29c1be3009",
      "author": {
        "kind": "user",
        "userId": "f3e7a668-7e78-44f2-bc92-4457a9a54337",
        "name": "Fixture Admin"
      },
      "body": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "text": "From Ada",
                "type": "text"
              }
            ]
          }
        ]
      },
      "text": "From Ada",
      "mentions": [],
      "createdAt": "2026-10-13T01:09:34.271Z",
      "editedAt": null,
      "url": "https://app.processcart.com/runs/3245e6a5-3fbe-463a-ad0b-a7fd871957b0?task=details"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

POST /v1/runs/{id}/comments

Comment on a task. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key. Operation id createRunComment · open in the API reference.

Posts a comment on one of the run's tasks as the API key (author.kind = api). Send plain text or a rich body — never both. The body is sanitized strictly: unknown node and mark types are dropped, a mention's label is re-derived from the member list, and a mention of a non-member is removed. Mentioned members are notified. Comments never change the run's revision. Refused on an archived or trashed run.

Path parameters

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

Request headers

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

Request body — application/json, CreateRunCommentBody

Property	Type	Required	Description
`taskKey`	string	yes	The task to comment on (any task of the run).
`text`	string	no	Plain text: blank lines separate paragraphs, a single newline is a line break, and `@Name` becomes a mention when it matches exactly one member.
`body`	object	no	A rich-text document (ProseMirror JSON). Allowed node types: paragraph, text, heading, bulletList, orderedList, listItem, blockquote, codeBlock, hardBreak, horizontalRule, image, table, tableRow, tableCell, tableHeader, mention, mergeTag (attrs.fieldKey must be a valid field key, else dropped), embed (an https video src on YouTube, Loom or Vimeo, else removed); marks: bold, italic, code, link, textStyle, highlight. Anything else is dropped on save. A mention node is `{ type: "mention", attrs: { id: "<member user id>" } }` — its label is always re-derived from the member list.

Responses

Status	Meaning	Body
201	Created. `Location` names the new resource.	Comment
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; `run_archived` — Run is archived; `run_trashed` — Run is in Trash.	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 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 run_archived — Run is archived
409 run_trashed — Run is in Trash
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

{
  "taskKey": "details",
  "text": "Hello from the API\nsecond line"
}

Example response (201)

{
  "id": "32629d31-996c-48af-8637-261a6aea7eca",
  "runId": "3245e6a5-3fbe-463a-ad0b-a7fd871957b0",
  "taskKey": "details",
  "runTaskId": "7d6b86f6-5f67-4729-870c-ed29c1be3009",
  "author": {
    "kind": "api",
    "keyId": "d422b49f-a3f2-4244-b97e-8d50f25c3036",
    "name": "collab key"
  },
  "body": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Hello from the API"
          },
          {
            "type": "hardBreak"
          },
          {
            "type": "text",
            "text": "second line"
          }
        ]
      }
    ]
  },
  "text": "Hello from the API\nsecond line",
  "mentions": [],
  "createdAt": "2026-10-13T01:09:30.295Z",
  "editedAt": null,
  "url": "https://app.processcart.com/runs/3245e6a5-3fbe-463a-ad0b-a7fd871957b0?task=details"
}

GET /v1/runs/{id}/comments/{commentId}

Get a comment. Scope runs:read · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it). Operation id getRunComment · open in the API reference.

One live comment of the run — the resource a POST answered with (its Location). A deleted comment is a 404.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes
`commentId`	string (uuid)	yes

Responses

Status	Meaning	Body
200	OK.	Comment
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)

{
  "id": "32629d31-996c-48af-8637-261a6aea7eca",
  "runId": "3245e6a5-3fbe-463a-ad0b-a7fd871957b0",
  "taskKey": "details",
  "runTaskId": "7d6b86f6-5f67-4729-870c-ed29c1be3009",
  "author": {
    "kind": "api",
    "keyId": "d422b49f-a3f2-4244-b97e-8d50f25c3036",
    "name": "collab key"
  },
  "body": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "text": "Hello from the API",
            "type": "text"
          },
          {
            "type": "hardBreak"
          },
          {
            "text": "second line",
            "type": "text"
          }
        ]
      }
    ]
  },
  "text": "Hello from the API\nsecond line",
  "mentions": [],
  "createdAt": "2026-10-13T01:09:30.295Z",
  "editedAt": null,
  "url": "https://app.processcart.com/runs/3245e6a5-3fbe-463a-ad0b-a7fd871957b0?task=details"
}