Comments

Comments let you attach rich-text notes to any record — person, company, deal, meeting, or a custom object. They appear in the record's activity feed and are visible to everyone with access to the record.

The message field uses BlockNote JSON — a structured block format, not plain text or markdown. See Rich text format below for the shape.

Fields

Field	Type	Description
`message`	array	Rich text body in BlockNote JSON format (required)
`owner_id`	string	UUID of the record the comment is attached to (required)
`entity`	string	Entity type of the target record — `person`, `company`, `deal`, `meeting`, or a `c_*` custom object slug (required)

_id, _created_at, _updated_at, _created_by, and _updated_by are returned on responses but not settable on create.

Create a comment

POST /comments

{
  "message": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Follow up in two weeks — evaluating three vendors." }
      ]
    }
  ],
  "owner_id": "872aced7-8f28-4bc8-9c2b-2602cb943c0d",
  "entity": "person"
}

Returns the created comment:

{
  "_id": "741ad3d3-624b-42a0-b810-5254239ae158",
  "message": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Follow up in two weeks — evaluating three vendors." }
      ]
    }
  ],
  "owner_id": "872aced7-8f28-4bc8-9c2b-2602cb943c0d",
  "entity": "person",
  "_created_at": "2026-05-29T20:32:11.664Z",
  "_updated_at": null,
  "_created_by": "6948a85b-606f-49a1-84d9-7d7ca37e4aa6",
  "_updated_by": null
}

Get a comment

GET /comments/{id}

Returns a single comment by its UUID.

{
  "_id": "741ad3d3-624b-42a0-b810-5254239ae158",
  "message": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Follow up in two weeks — evaluating three vendors." }]
    }
  ],
  "owner_id": "872aced7-8f28-4bc8-9c2b-2602cb943c0d",
  "entity": "person",
  "_created_at": "2026-05-29T20:32:11.664Z",
  "_updated_at": null,
  "_created_by": "6948a85b-606f-49a1-84d9-7d7ca37e4aa6",
  "_updated_by": null
}

Update a comment

PATCH /comments/{id}

Only message can be updated. The target record (owner_id/entity) and authorship are preserved.

{
  "message": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Budget confirmed — closing next week." }]
    }
  ]
}

Returns the updated comment.

Delete a comment

DELETE /comments/{id}

Permanently deletes the comment. Returns 200 OK with the deleted comment body.

Rich text format

The message field uses BlockNote JSON — the same format Clarify's UI editor produces and the same format used by task descriptions. Each top-level entry is a block (paragraph, heading, bullet list item, etc.) with an array of inline text runs.

Minimum-viable example: a single paragraph.

{
  "message": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Follow up after the meeting on " },
        { "type": "text", "text": "Tuesday", "styles": { "bold": true } },
        { "type": "text", "text": " with the proposal." }
      ]
    }
  ]
}

Common block types: paragraph, heading (with props.level: 1–3), bulletListItem, numberedListItem, checkListItem. Inline text runs accept styles: bold, italic, underline, strike, code.

If you only need plain text, the simplest payload is one paragraph with a single text run:

{ "message": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Plain text body." }] }] }