Bulk create comments

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

Create up to 50 comments in one request. Each row is validated and written exactly as Create a comment would, so every business rule and permission check still applies per row.

200 does not mean every row succeeded

By default this endpoint reports partial success: it returns 200 whenever it processed the batch, even if some rows failed. Check failed and the per-row results instead of relying on the status code alone.

For all-or-nothing behavior, send all_or_none: true and treat 409 as failure.

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 comments belong to. Accepts the project UUID or its bare identifier, for example ENG.

work_item_id:requiredstring (uuid)

The work item the comments belong to. Accepts the work item UUID or its PROJ-123 identifier.

Body parameters

items:requiredarray of object

The comments to create. Each entry takes the same body as Create a comment. Between 1 and 50 per call.

To make a row a reply, set its parent_id to an existing top-level comment on the work item. A row can't reply to another row in the same batch, because the new comments have no ids until the call returns.

all_or_none:optionalboolean

Defaults to false, which gives partial success: each row runs in its own savepoint, successful rows are committed, and the response reports the outcome of each row.

Set it to true to make the batch atomic. Every row is still evaluated, but if any row fails, the whole batch is discarded and the call returns 409 instead of the 200 envelope. Side effects that the rows schedule are kept or discarded along with the batch.

Scopes

projects.work_items.comments:write

Errors

Status	Code	Cause
400	invalid_request	The envelope is malformed: items is missing or empty, has more than 50 rows, or contains an id that isn't a UUID.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't write comments in this project.
404	not_found	No such workspace or project, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	An all_or_none: true batch had at least one failing row, so the whole batch was discarded.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The body wasn't JSON. These routes accept JSON only, and a form or multipart body can't express items.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Bulk create comments

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/comments/bulk-create/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "comment_html": "<p>Reproduced on staging.</p>"
    },
    {
      "comment_html": "<p>Reproduced on staging.</p> 2"
    }
  ]
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/comments/bulk-create/",
    headers={"X-Api-Key": "your-api-key"},
    json={
    "items": [
        {
            "comment_html": "<p>Reproduced on staging.</p>"
        },
        {
            "comment_html": "<p>Reproduced on staging.</p> 2"
        }
    ]
},
)
body = response.json()
print(body["succeeded"], body["failed"])

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/comments/bulk-create/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      items: [
        {
          comment_html: "<p>Reproduced on staging.</p>",
        },
        {
          comment_html: "<p>Reproduced on staging.</p> 2",
        },
      ],
    }),
  },
);
const body = await response.json();
console.log(body.succeeded, body.failed);

Response200

{
  "results": [
    {
      "index": 0,
      "result": "created",
      "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53"
    },
    {
      "index": 1,
      "result": "failed",
      "type": "invalid_request",
      "code": "invalid_request",
      "detail": "One or more fields failed validation.",
      "errors": [
        {
          "field": "name",
          "code": "unique",
          "message": "A comment with this name already exists."
        }
      ]
    }
  ],
  "succeeded": 1,
  "failed": 1
}

Response409

{
  "type": "conflict",
  "code": "conflict",
  "detail": "No rows were written because all_or_none was set and at least one row failed.",
  "errors": [
    {
      "field": "items.1.name",
      "code": "unique",
      "message": "A comment with this name already exists."
    }
  ]
}

Reading the response

The 200 envelope has three members:

• results: one entry per input row, in request order, each with its index
• succeeded and failed: counts, so you can branch without walking the array

A successful row is { index, result, id }, where result is created. A failed row has the same members as a top-level error body (type, code, detail, and errors[] on validation failures) plus index and result: "failed", so the code that handles top-level errors also works per row. See Errors.

Atomic batches

With all_or_none: true, every row is still evaluated, so you see every row that would have failed, not only the first, before the batch is rolled back. Each entry in the 409 body's errors[] is prefixed with the row index, as items.<index>.<field>, so you can trace each error back to its row.

Because the rollback covers the whole batch, side effects scheduled on commit, such as activity feed entries and webhooks, are discarded with it.

Limits and related routes

• Each call takes between 1 and 50 rows. Sending more than 50 fails the whole request with 400.
• These routes accept JSON only. A form or multipart body can't express items, so they reject it with 415 instead of misreading the payload.
• Bulk endpoints don't reconcile on external ids. To do that, use Upsert a comment per row, or list and diff.
• ?fields= doesn't apply here. The response is a per-row result envelope, not a comment body. See Sparse fields.