Post a comment on a drive item

POSThttps://<your-url>/api/v2/drive-items/{drive_item}/comments

MCP id drive-items.comments.storeAlso on this path: GET List a drive item's comments

Creates one comment on the drive item named in the path, authored as the authenticated user, and returns it in the detail view with a Location header pointing at its flat path /comments/{comment}, where it is read, edited and deleted.

Token scope: api:write:project_driveorapi:write:customer_driveorapi:write:organization_driveorapi:write:user_drive
Without it: 403 insufficient-token-scope.
Permission: project_drive::create
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: A comment on a drive document

curl -X POST \
  'https://<your-url>/api/v2/drive-items/1/comments' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "body": "<p>Section 3 needs the new pricing table.</p>"
  }'

const response = await fetch('https://<your-url>/api/v2/drive-items/1/comments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "body": "<p>Section 3 needs the new pricing table.</p>"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/drive-items/1/comments', [
        'body' => '<p>Section 3 needs the new pricing table.</p>',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/drive-items/1/comments',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'body': '<p>Section 3 needs the new pricing table.</p>'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "body": "<p>Section 3 needs the new pricing table.</p>",
    "author_type": "user",
    "author_id": 1,
    "author": {
      "id": 1
    },
    "commentable_type": "work_item",
    "commentable_id": 1,
    "commentable": {
      "id": 1
    },
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

body is the only accepted key: the drive item comes from the path, so commentable_type and commentable_id in the body are a 422, and the author is the caller, so author_type and author_id are never accepted. Commenting is a reader's right on a drive item (the same rule the document editor's comment box applies), so the item's access only has to grant view, not edit. Posting works exactly like posting in the editor, so mention notifications, thread events and the author's auto-subscription all fire. The body is rich text: mention spans read from an existing comment may be posted back verbatim and are preserved, but constructing a new mention is not supported in v2.0. An archived drive item is 404.

Path parameters

drive_itemintegerRequired

The DriveItem's numeric id. Accepts a soft-deleted record.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

bodystring≤ 65535Required

Comment body as rich text. HTML from the plnnrly editor, sanitised on the way out, so what you read back can differ from the bytes you sent. Mention spans (<span data-type="mention" data-id="3">) survive untouched and may be posted back verbatim; constructing a new mention is not supported in v2.0.

Response 201

Returns a Comment in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning