Work item comments overview

A comment is a note posted on a single work item. Comments are a sub-resource of a work item, not a project-level collection: every route is mounted under the work item, so a comment can only be read or written through the work item it belongs to.

/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/

That means the collection routes carry three path parameters (slug, project_id, work_item_id) and the detail routes carry four (plus pk). There is no workspace-wide or project-wide comment feed. To gather comments across work items, list them per work item.

Learn more about work item comments

The comment object

Attributes

• id string (uuid)

  Unique identifier for the comment.

• work_item_id string (uuid)

  The work item this comment is attached to. Always matches the work_item_id in the request path.

• parent_id string (uuid) or null

  The top-level comment this comment replies to, or null for a top-level comment. See Replies.

• comment_html string

  The comment body, as HTML. This is the field you write.

• comment_stripped string

  The plain-text version of comment_html, derived server-side. It is what ?search= matches, so markup never affects a search hit. It is read-only, so you never send it.

• access string

  Visibility of the comment. One of INTERNAL or EXTERNAL. INTERNAL keeps the comment inside the project team; EXTERNAL marks it as visible outside the team, for example on a published project.

• actor_id string (uuid) or null

  The author of the comment, meaning the principal that posted it. Set server-side from the authenticated caller, so you cannot post a comment on someone else's behalf.

• edited_at string (date-time) or null

  When the comment was last updated through a PATCH. null on a comment that has never been edited. Clients use it to decide whether to show an "edited" marker.

• hidden_at string (date-time) or null

  When the comment was hidden from the discussion, or null if it is visible. Read-only. The API returns hidden comments like any other, so check this field before you display a body.

• hidden_by_id string (uuid) or null

  The user who hid the comment, or null. Read-only.

• hidden_reason string or null

  Why the comment was hidden. One of abuse, spam, off_topic, sensitive_info, or other, or null when the comment is not hidden. Read-only.

• external_id , external_source string or null

  Correlation fields for sync and import. Together they let you map a comment to a record in another system and find it again with ?external_id= and ?external_source=.

• created_at string (date-time)

  When the comment was created.

• updated_at string (date-time)

  When the comment was last updated.

• created_by_id string (uuid) or null

  The user record that created the comment. For comments posted by a person this is the same user as actor_id; actor_id is the domain field that Plane renders as the comment author.

• updated_by_id string (uuid) or null

  The user who last updated the comment. null until someone updates it.

Write comment_html, read comment_stripped

comment_html is the only body field you can set. Plane derives comment_stripped from it on every write, so the two never drift apart.

Response200

{
  "id": "c1f7a3d9-2b64-4f80-9c1a-3d5e8b2a6c47",
  "work_item_id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
  "parent_id": null,
  "comment_html": "<p>Deployed the fix to staging. Please re-test.</p>",
  "comment_stripped": "Deployed the fix to staging. Please re-test.",
  "access": "INTERNAL",
  "actor_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "external_id": null,
  "external_source": null,
  "edited_at": null,
  "hidden_at": null,
  "hidden_by_id": null,
  "hidden_reason": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/	List comments
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/{pk}/	Get a comment
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/	Create a comment
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/{pk}/	Update a comment
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/{pk}/	Delete a comment
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/upsert/	Upsert a comment
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/bulk-create/	Bulk create comments
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/bulk-update/	Bulk update comments
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/comments/bulk-delete/	Bulk delete comments

Comments are not deduplicated

The API will not collapse duplicates for you

Nothing about a comment's body or external_id identifies it uniquely, so posting the same comment_html twice creates two comments. If your integration must post a comment at most once, send an external_id and look for it first with GET …/comments/?external_id=…&external_source=… before creating.

Writes can still fail with 409 conflict, so branch on the code in the problem response instead of assuming a create always succeeds.

Replies

A comment with a parent_id is a reply. Send parent_id on create, update, upsert, or a bulk row to make one.

• Replies are one level deep. The parent must be a top-level comment, so a reply to a reply returns 400.
• Plane doesn't stop you from moving a top-level comment that has replies under another comment. Its replies stay attached to it, so the thread ends up two levels deep. Check for replies before you set parent_id on a top-level comment.
• The parent must be on the same work item. A parent on another work item returns 400 on parent_id, and so does a comment that points at itself.
• A reply takes its parent's access. The parent's access replaces whatever access you send with a reply.
• PATCH a reply with "parent_id": null to make it a top-level comment.

Lists are flat, and a reply is a row of its own. Group rows by parent_id to rebuild threads.

Access and visibility

access is set per comment and can be changed later with a PATCH. Filter a list down to one visibility with ?access=INTERNAL or ?access=EXTERNAL when you need only the comments a particular audience can see.

Changing access on a top-level comment also changes it on every reply to that comment.

Reads follow the parent work item

Comment visibility is inherited from the work item in the path. There is no per-comment read permission. A pk that belongs to a different work item is not visible on this route and returns 404 not_found, the same as a comment id that does not exist, so the response never reveals whether the comment exists.

Changed from v1

• The path segment is /work-items/{work_item_id}/comments/ and the parent id is reported as work_item_id instead of issue.
• actor is now actor_id, and created_by is now created_by_id.
• updated_by, parent, and hidden_by are now updated_by_id, parent_id, and hidden_by_id.
• Reads no longer return deleted_at, project, workspace, comment_json, attachments, is_member, or is_hidden. A comment is hidden when hidden_at is set.
• edited_at is stamped by Plane on every PATCH.

See Migrating from v1 for the full list.