# POST /api/v2/drive-items/{drive_item}/comments

Post a comment on a drive item

- MCP id: drive-items.comments.store
- Scope: api:write:project_drive
- Scope: api:write:customer_drive
- Scope: api:write:organization_drive
- Scope: api:write:user_drive
- Permission: project_drive::create
- Rate cost: 1 unit, write bucket. A write costs the same whatever `view` you ask for.
- Cache-Control: private, no-store

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.

`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`.

## Parameters
- drive_item (integer, path): The DriveItem's numeric id. Accepts a soft-deleted record.
- view (string, optional): Which field set to render.
- X-Request-Id (header, optional): 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-Key (header, optional): A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

## Request body
- body (string ≤ 65535, required): 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.

Unknown keys are refused with `422` validation-failed, naming the key.

## Response 201
- id (integer, required): Unique identifier.
- body (html, required): 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.
- author_type (string, required): The kind of record `author` points at; it says which branch of `author` applies.
- author_id (integer, required): The id of the record `author` points at.
- author (Ref or UserSummary, required): Who wrote the comment. Renders as `{"id": N}` unless `?include=author` expands it, which additionally requires the users prefix's read grant and a token covering it.
- commentable_type (string, required): The kind of record `commentable` points at; it says which branch of `commentable` applies.
- commentable_id (integer, required): The id of the record `commentable` points at.
- commentable (Ref, required): The record the comment hangs off, as a reference. Look it up from `commentable_type` and `commentable_id` with `GET /api/v2/work-items/{id}` or GET `/api/v2/drive-items/{id}`. It is not expandable: `?include=commentable` is a `400`.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): When the comment was posted.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync, and as the revision the strong `ETag` is derived from.
- links (CommentLinks, required)
  - self (url, required): The canonical URI of this record.

## Errors
- 403 forbidden-by-policy | insufficient-permission | insufficient-token-scope: Forbidden.
- 409 idempotency-key-in-flight | idempotency-key-reused: Conflict.
- 415 unsupported-media-type: Unsupported media type.
- 422 unprocessable-relationship | validation-failed: Unprocessable content.
- 400 idempotency-key-required | invalid-cursor | invalid-query-parameter | malformed-request | unsupported-parameter: Bad request.
- 401 token-expired | unauthenticated: Unauthenticated.
- 404 endpoint-not-found | resource-not-found: Not found.
- 406 not-acceptable: Not acceptable.
- 429 rate-limit-exceeded: Too many requests.
- 500 internal-error: Server error.
- 503 tenant-unavailable: Service unavailable.

## Example
```bash
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>"
  }'
```