Comments

Add, edit, delete, and retrieve comments on posts. Supports threaded replies.

Endpoints

List comments on a post

Scope

comments:read

Parameters

idstringrequiredPost ID (URL path)

Response

{
  "comments": [
    {
      "id": "cmt_abc123",
      "content": "Great update! Love the progress.",
      "parentId": null,
      "createdAt": "2024-02-01T14:00:00Z",
      "updatedAt": "2024-02-01T14:00:00Z",
      "author": {
        "id": "usr_def456",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "image": "/api/media/avatars/jane.jpg"
      }
    }
  ]
}

Add a comment to a post

Scope

comments:write

Parameters

idstringrequiredPost ID (URL path)

contentstringrequiredComment content (max 5,000 chars)

parentIdstringParent comment ID for threaded replies

Edit a comment (author only)

Scope

comments:write

Parameters

idstringrequiredPost ID (URL path)

commentIdstringrequiredComment ID (URL path)

contentstringrequiredNew comment content (max 5,000 chars)

Delete a comment

Scope

comments:write

Parameters

idstringrequiredPost ID (URL path)

commentIdstringrequiredComment ID (URL path)

Attachments

To attach a file (any type except raster images and videos, which use the Cloudflare Images/Stream flows) to a comment, call POST /api/v1/media with a commentId in the request body. Up to 10 attachments per comment. See the Media API reference for upload format, supported file types, and size limits.

Threaded Replies

To create a reply to an existing comment, include the parentId parameter with the ID of the comment you want to reply to. Omit this parameter for top-level comments.

The response includes the parentId field which is null for top-level comments and contains the parent comment ID for replies.

Editing & Deleting

Only the comment author can edit a comment. Deleting a comment is allowed for the comment author, the post author, or workspace admins/owners. Deletion is a soft delete — the comment is marked as deleted but not permanently removed.

Mentions

You can mention users in comments using the @username syntax in the comment content. Mentioned users will receive a notification.

Permissions

Reading comments requires the comments:read scope. Creating, editing, and deleting comments requires the comments:write scope.