​
Comments API

Comments provide item-level discussion threads in ProBeya. Each comment is attached to a specific item and stores rich text content as Tiptap JSON (JSONB). Comments support @mentions, and the system automatically notifies the item creator when others comment.

​
Authorization Rules

  • Any organization member can create comments on items within their org
  • Only the comment author can update or delete their own comments
  • Comments are tenant-isolated via the parent item’s organizationId

​
Endpoints

​
GET /api/v1/items/:id/comments

List all comments for a specific item, ordered chronologically (oldest first). Includes author information for rendering avatars and display names.

tRPC: comments.list Auth: Bearer token required (scope: read:items) or session cookie Org context: Required

Parameters:

NameTypeRequiredDescription
idstring (path)YesThe item ID to fetch comments for

Example:

curl -H "Authorization: Bearer probeya_sk_live_..." \
     https://acme.probeya.com/api/v1/items/clx9it001/comments

Response:

{
  "data": [
    {
      "id": "clx9cm001",
      "itemId": "clx9it001",
      "authorId": "clx9us002",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              { "type": "text", "text": "Calibration completed. Results within spec." }
            ]
          }
        ]
      },
      "createdAt": "2026-03-28T10:30:00.000Z",
      "updatedAt": "2026-03-28T10:30:00.000Z",
      "author": {
        "id": "clx9us002",
        "name": "Jane Smith",
        "email": "[email protected]",
        "image": "https://cdn.probeya.com/avatars/clx9us002.jpg"
      }
    },
    {
      "id": "clx9cm002",
      "itemId": "clx9it001",
      "authorId": "clx9us001",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              { "type": "text", "text": "Great, please attach the certificate." }
            ]
          }
        ]
      },
      "createdAt": "2026-03-28T11:00:00.000Z",
      "updatedAt": "2026-03-28T11:00:00.000Z",
      "author": {
        "id": "clx9us001",
        "name": "John Doe",
        "email": "[email protected]",
        "image": null
      }
    }
  ]
}

Errors:

CodeDescription
401Missing or invalid authentication
404Item not found in this organization

​
POST /api/v1/items/:id/comments

Add a new comment to an item. The author is automatically set to the authenticated user. Content is stored as Tiptap JSON for rich text rendering.

tRPC: comments.create Auth: Bearer token required (scope: write:items) or session cookie Org context: Required

Parameters:

NameTypeRequiredDescription
idstring (path)YesThe item ID to comment on
contentobjectYesTiptap JSON document (rich text content)

Request body:

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Certificate attached. Closing this item." }
        ]
      }
    ]
  }
}

Response:

{
  "data": {
    "id": "clx9cm003",
    "itemId": "clx9it001",
    "authorId": "clx9us002",
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "Certificate attached. Closing this item." }
          ]
        }
      ]
    },
    "createdAt": "2026-03-30T15:00:00.000Z",
    "updatedAt": "2026-03-30T15:00:00.000Z"
  }
}

Side effects:

  • Notifies the item creator when someone else comments on their item
  • No self-notifications (if the commenter is the item creator)

Errors:

CodeDescription
401Missing or invalid authentication
403Insufficient scope (write:items required)
404Item not found in this organization

​
Rich Text Content Format

Comments use the Tiptap JSON document format. A minimal plain-text comment looks like:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Your comment text here." }
      ]
    }
  ]
}

Supported node types include paragraph, heading, bulletList, orderedList, listItem, codeBlock, blockquote, hardBreak, and inline marks like bold, italic, code, link, and mention.

​
tRPC-Only Comment Procedures

ProcedureDescription
comments.updateEdit own comment content (author-only)
comments.deleteDelete own comment (author-only, permanent)

Was this page helpful?

Actions APISearch API