Create a comment

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

Post a comment on a work item. The comment is attached to the work item in the path and appears in its discussion immediately.

The author is taken from the credentials on the request and returned as actor_id, so you cannot post a comment on behalf of another user.

To reply to a comment, send its id as parent_id. The reply comes back with that parent_id set.

Comments are not deduplicated

Nothing about a comment's body or external_id identifies it uniquely, so sending 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=….

Path parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring (uuid)

The project the work item belongs to.

work_item_id:requiredstring (uuid)

The work item to comment on.

Body parameters

comment_html:requiredstring

The comment body, as HTML, for example <p>Deployed the fix to staging.</p>. Plane derives the plain-text comment_stripped from it server-side, which is what search matches.

access:optionalstring

Visibility of the comment.

• INTERNAL: visible to the project team
• EXTERNAL: marked as visible outside the team, for example on a published project

Omit it to take the server's default. Change it later with a PATCH.

parent_id:optionalstring (uuid)

Post the comment as a reply to this comment. Replies are one level deep, so the parent must be a top-level comment on the same work item. A reply to a reply, or a parent on another work item, returns 400 on parent_id. Omit it or send null for a top-level comment.

A reply takes its parent's access, whatever you send in access.

external_id:optionalstring

Your system's identifier for this comment, for sync and import correlation. Maximum 255 characters. Accepts null.

external_source:optionalstring

The system external_id came from, for example github or zendesk. Maximum 255 characters. Accepts null.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.

Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.

Requestable here: access, actor_id, comment_html, comment_stripped, created_at, created_by_id, edited_at, external_id, external_source, hidden_at, hidden_by_id, hidden_reason, id, parent_id, updated_at, updated_by_id, work_item_id.

See Sparse fields.

expand:optionalstring

Comma-separated relations to embed alongside the ids: actor (the comment author).

Expanded objects get their own key: ?expand=state keeps state_id and adds a state object next to it, so an id is never replaced by an object. An unknown value returns 400.

?fields= and ?expand= take separate sets of names. Relation names aren't valid in ?fields=, field names aren't valid in ?expand=, and field filtering never removes an expanded object: ?fields=id,name&expand=state returns id, name and state. See Expanding relations.

Scopes

projects.work_items.comments:write

Errors

Status	Code	Cause
400	invalid_request	Missing comment_html, an access value outside the enum, or a parent_id that isn't a top-level comment on this work item.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	Your role or token scope can't comment on this work item.
404	not_found	No such workspace, project, or work item, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	The write conflicts with the current state of the work item.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Create a comment

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/comments/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "comment_html": "<p>Deployed the fix to staging. Please re-test.</p>",
  "access": "INTERNAL"
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/comments/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "comment_html": "<p>Deployed the fix to staging. Please re-test.</p>",
        "access": "INTERNAL",
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/comments/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      comment_html: "<p>Deployed the fix to staging. Please re-test.</p>",
      access: "INTERNAL",
    }),
  },
);
const data = await response.json();

Response201

{
  "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
}

Response400

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "The request body failed validation.",
  "errors": [
    {
      "field": "comment_html",
      "code": "required",
      "message": "This field is required."
    }
  ]
}

Response400

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "The request body failed validation.",
  "errors": [
    {
      "field": "parent_id",
      "code": "invalid",
      "message": "Must be a top-level comment on the same work item."
    }
  ]
}