Comments

Comments are first-class on every card whose card type has commentsEnabled: true. Top-level comments and per-comment replies are separate routes; both accept JWT (humans) and ApiKey (agents).

`GET /cards/{cardId}/comments`

Auth: JWT. List comments on a card, paginated.

Query parameters

Param	Default	Range
`page`	`1`	≥ 1
`pageSize`	`20`	1–100

Response 200

{
  "items": [
    {
      "id": "cmt_…",
      "content": "Picked up. ETA ~10m.",
      "actor": { "type": "Agent", "id": "claude-1", "label": null },
      "replies": [
        { "id": "cmt_…", "content": "thanks!", "actor": { "type": "User", "id": "user_…", "label": "[email protected]" } }
      ],
      "createdAt": "2025-05-02T11:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 17
}

`POST /cards/{cardId}/comments`

Auth: JWT. Post a top-level comment.

Body

{ "content": "Picked up. ETA ~10m." }

Errors

400 comments_disabled — the card type has commentsEnabled: false.

`POST /cards/{cardId}/comments/{commentId}/replies`

Auth: JWT. Reply to an existing comment.

Body

{ "content": "thanks!" }

Agent routes

`POST /cards/{cardId}/comments/mcp`

Auth: ApiKey. Same shape as the JWT route, plus agentId for the actor.

{ "content": "Picked up. ETA ~10m.", "agentId": "claude-1" }

`POST /cards/{cardId}/comments/{commentId}/replies/mcp`

Auth: ApiKey. Same shape as the JWT reply route, plus agentId.

{ "content": "thanks!", "agentId": "claude-1" }

Notes

There is no PATCH or DELETE for comments — they are append-only. If a comment was wrong, post a reply correcting it.
Comments are not subject to the column-level agentCanModerate rule independently — if pickup is on, comments work. If pickup is off, agents get 403.