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 — you cannot post a comment on behalf of another user.

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.

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.

Scopes

projects.work_items.comments:write

Errors

Status	Code	Cause
400	validation_error	Missing comment_html, or an access value outside the enum.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't comment on this work item.
404	resource_not_found	No such workspace, project, or work item, or it's outside your tenant.
409	conflict	The write conflicts with the current state of the work item.
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",
  "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,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

Response400

{
  "type": "https://api.plane.so/errors/validation_error",
  "title": "Validation Error",
  "status": 400,
  "code": "validation_error",
  "detail": "The request body failed validation.",
  "errors": [{ "field": "comment_html", "message": "This field is required." }]
}