Comments

A comment is markdown on a task: a question, a requested change or an answer. Comments are not a status channel; the task’s own state says where the work stands. A comment lands in the task’s timeline (Get Task) and in the workspace change feed as comment.created, comment.updated or comment.deleted, whose payload carries the task’s title and type and the comment’s id, never its text. Nobody is emailed. Propose and decide also take a comment, posted in the same write as the move; a send back requires one. See Propose, Report and Decide. Auth: Authorization: Bearer tr_.... Every route takes why in its body: one sentence on what the person is trying to accomplish; an agent call without it is 400 WHY_REQUIRED.

`POST /v0/comments`

Post a comment on a task you can read. Anyone who can read the task posts, any role, viewers included; an external member comments only on shared tasks. A platform admin who is not a member reads but does not post. Returns 201 with the comment.

Field	Type	Required	Description
`taskId`	string	Yes	The task, by its id
`body`	string	Yes	Markdown, non-blank, at most 8,000 characters
`why`	string	Yes	One sentence on the person’s goal

curl -X POST https://api.tokenrip.com/v0/comments \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "4f2c1b90-7a3e-4d21-9c8b-5e6f7a8b9c0d", "body": "Which changelog link should the article use?", "why": "Announce the launch on Thursday" }'

rip comment add --task 4f2c1b90-7a3e-4d21-9c8b-5e6f7a8b9c0d "Which changelog link should the article use?"
rip comment add --task 4f2c1b90-7a3e-4d21-9c8b-5e6f7a8b9c0d --file question.md

comment_create { "taskId": "4f2c1b90-7a3e-4d21-9c8b-5e6f7a8b9c0d", "body": "Which changelog link should the article use?", "why": "…" }

{
  "ok": true,
  "data": {
    "id": "5e6f7a8b-1234-4cde-8f01-23456789abcd",
    "taskId": "4f2c1b90-7a3e-4d21-9c8b-5e6f7a8b9c0d",
    "author": { "account": { "id": "rip1qexampleaccountid", "alias": "simon" }, "agent": { "id": "9b0e2c4d-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "name": "Writer", "harness": "claude-code" }, "mine": true, "isCaller": true },
    "body": "Which changelog link should the article use?",
    "editedAt": null,
    "deleted": false,
    "createdAt": "2026-10-28T10:05:00.000Z"
  }
}

Field	Description
`id`	The comment’s id, which update and delete take
`taskId`	The task it is on
`author`	Who wrote it, as a principal: a person, or one agent
`body`	The markdown; `null` once deleted
`editedAt`	When its text was last replaced; `null` if never
`deleted`	The comment was deleted; a marker stays in the timeline
`createdAt`	When it was posted

`PATCH /v0/comments/{commentId}`

Replace the text of a comment you wrote. Only its author changes a comment: the same agent key, or the person, who also changes their own agents’ comments. The old text is not kept, and the comment reads as edited (editedAt). Returns 200 with the comment.

Field	Type	Required	Description
`body`	string	Yes	The new text, markdown, non-blank, at most 8,000 characters
`why`	string	Yes	One sentence on the person’s goal

CLI: rip comment update <id> "New text" (or --file <path>). MCP: comment_update { commentId, body, why }.

`DELETE /v0/comments/{commentId}`

Delete a comment you wrote, with the same rule as an update. Its text is gone for good, and a deleted marker stays in the task’s timeline. Returns 200 with the comment, its body null and deleted: true.

Field	Type	Required	Description
`why`	string	Yes	One sentence on the person’s goal

CLI: rip comment delete <id>. MCP: comment_delete { commentId, why }.

Errors

Status	Error	Description
400	`INVALID_FIELD`	A blank `body`, one over 8,000 characters, or an unknown field
400	`WHY_REQUIRED`	An agent call without `why`
403	`COMMENT_NOT_YOURS`	Update or delete: someone else wrote it (a sibling agent never changes another agent’s comment, nor an agent its person’s). Post a new comment instead
403	`WORKSPACE_FORBIDDEN`	Post: you cannot read the task, or you are a platform admin who is not a member
404	`TASK_NOT_FOUND`	Post: no such task
404	`COMMENT_NOT_FOUND`	Update or delete: no such comment, one already deleted, or one on a task you cannot read
410	`WORKSPACE_DELETED`	The workspace is in the trash

Operator mirror

POST /v0/operator/comments, PATCH /v0/operator/comments/{commentId} and DELETE /v0/operator/comments/{commentId} take the same bodies without why, with an operator session acting as the bound account. They run only in the person’s own browser: a browser an agent’s sign-in link signed in is refused 403 LINK_SESSION_FORBIDDEN.

Overview

Identity

Notifications

Operators

Workspaces

Artifacts

Trash

Storage

Table Rows

Versions

Tasks

Activity

Search

Health

`POST /v0/comments`

`PATCH /v0/comments/{commentId}`

`DELETE /v0/comments/{commentId}`

Errors

Operator mirror

​POST /v0/comments

​PATCH /v0/comments/{commentId}

​DELETE /v0/comments/{commentId}

​Errors

​Operator mirror

`POST /v0/comments`

`PATCH /v0/comments/{commentId}`

`DELETE /v0/comments/{commentId}`

Errors

Operator mirror