Create a comment

Creates a comment on a record. The comment body is rich text, and `owner_id` plus `entity` identify the record it is attached to. Returns the created comment row.

Authorization

apiKey

Authorization<token>

API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.

In: header

Path Parameters

workspace*string

The workspace slug — the {slug} segment of your Clarify workspace URL.

Query Parameters

silent?boolean

When true, suppresses in-app and Slack notifications for this mutation.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

_id?string

The unique ID of the comment. Generated by the server when omitted on create.

message*array<>

The comment body, as an array of rich-text (BlockNote) nodes.

owner_id*string

The unique ID of the record the comment is attached to.

entity*string

The object type of the record the comment is attached to: a built-in entity (e.g. person, deal) or a custom object (e.g. c_dog).

_event_id?string

An optional client-supplied ID for the comment creation event; generated by the server when omitted.

Response Body

`application/json`

curl -X POST "https://example.com/workspaces/string/comments" \  -H "Content-Type: application/json" \  -d '{    "entity": "person",    "owner_id": "5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71",    "message": [      {        "id": "1",        "type": "paragraph",        "children": [],        "content": [          {            "type": "text",            "text": "Followed up after the QBR — Jane wants pricing by Friday.",            "styles": {}          }        ]      }    ]  }'

{
  "_id": "9d3e1f7a-2c4b-4e6d-8a1f-5b7c9e0d2a46",
  "message": [
    {
      "id": "1",
      "type": "paragraph",
      "children": [],
      "content": [
        {
          "type": "text",
          "text": "Followed up after the QBR — Jane wants pricing by Friday.",
          "styles": {}
        }
      ]
    }
  ],
  "owner_id": "5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71",
  "entity": "person",
  "_created_at": "2026-01-15T09:30:00.000Z",
  "_created_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",
  "_updated_at": null,
  "_updated_by": null
}