​
Overview

Comments allow threaded discussions on items. Each comment can contain rich text, @mentions, and file attachments.

​
List Comments

List all comments on an item. 
GET /api/trpc/comments.list?input={"json":{"itemId":"itm_01HXK5..."}}
Input Parameters:
ParameterTypeRequiredDescription
itemIdstringYesItem ID
cursorstringNoPagination cursor
limitnumberNoResults per page (default: 50)
Response: 
{
  "result": {
    "data": {
      "json": {
        "comments": [
          {
            "id": "cmt_01HXK5QJBN3YZXM8KJP2RSNV4C",
            "itemId": "itm_01HXK5...",
            "parentId": null,
            "body": "I've updated the wireframes based on the feedback from @usr_01HXK6...",
            "bodyHtml": "<p>I've updated the wireframes based on the feedback from <span class=\"mention\">@Alice</span></p>",
            "mentions": ["usr_01HXK6..."],
            "attachments": [
              {
                "id": "att_01HXK5...",
                "name": "wireframe-v2.png",
                "url": "https://acme.obeya.cloud/storage/...",
                "size": 245000,
                "type": "image/png"
              }
            ],
            "reactions": [
              { "emoji": "thumbsup", "users": ["usr_01HXK5...", "usr_01HXK6..."] }
            ],
            "author": {
              "id": "usr_01HXK5...",
              "name": "Bob Smith",
              "avatar": "https://..."
            },
            "replyCount": 2,
            "isPinned": false,
            "createdAt": "2026-03-18T10:00:00.000Z",
            "updatedAt": "2026-03-18T10:00:00.000Z"
          }
        ],
        "nextCursor": null
      }
    }
  }
}

​
Get Comment Replies

List replies to a specific comment (thread). 
GET /api/trpc/comments.replies?input={"json":{"commentId":"cmt_01HXK5..."}}
Response: 
{
  "result": {
    "data": {
      "json": {
        "replies": [
          {
            "id": "cmt_01HXK6...",
            "parentId": "cmt_01HXK5...",
            "body": "Looks great! Approved.",
            "author": {
              "id": "usr_01HXK6...",
              "name": "Alice Johnson",
              "avatar": "https://..."
            },
            "createdAt": "2026-03-18T11:00:00.000Z"
          }
        ]
      }
    }
  }
}

​
Create Comment

Post a new comment on an item. 
POST /api/trpc/comments.create
Request: 
{
  "json": {
    "itemId": "itm_01HXK5...",
    "body": "The implementation looks good. @usr_01HXK6... can you review the edge cases?",
    "parentId": null
  }
}
FieldTypeRequiredDescription
itemIdstringYesItem ID to comment on
bodystringYesComment text (supports Markdown)
parentIdstringNoParent comment ID (for threaded replies)
attachmentIdsstring[]NoIDs of pre-uploaded files to attach
@mentions are automatically parsed from the comment body. Use the format @usr_ID to mention a specific user. The API will resolve the user and send notifications.

​
Update Comment

Edit a comment. Only the comment author can edit their own comments. 
POST /api/trpc/comments.update

{
  "json": {
    "id": "cmt_01HXK5...",
    "body": "Updated: The implementation looks good. Ready for merge."
  }
}

​
Delete Comment

Delete a comment. Authors can delete their own comments. Admins can delete any comment. 
POST /api/trpc/comments.delete

{
  "json": {
    "id": "cmt_01HXK5..."
  }
}

​
Pin Comment

Pin a comment to the top of the comment section. 
POST /api/trpc/comments.pin

{
  "json": {
    "id": "cmt_01HXK5...",
    "pinned": true
  }
}

​
Add Reaction

Add an emoji reaction to a comment. 
POST /api/trpc/comments.react

{
  "json": {
    "commentId": "cmt_01HXK5...",
    "emoji": "thumbsup"
  }
}
To remove a reaction, send the same request — reactions toggle on/off.

​
Available Reactions

EmojiCode
Thumbs Upthumbsup
Thumbs Downthumbsdown
Heartheart
Checkmarkcheck
Eyeseyes
Rocketrocket
Partyparty
Thinkingthinking
Use reactions instead of comments for simple acknowledgments. They are lightweight and do not generate comment notifications.