# Comment

A comment on a work item or on a drive item: the rich-text body one user posted to a thread, with its author and its timestamps. Comments are reached through their parent (GET `work-items/{work_item}/comments`) or by id on the flat item path, and the parent is named by the `commentable_type` / `commentable_id` pair rather than by an expandable relation. Editing and deleting are author-only.

## Used by
- GET /api/v2/comments/{comment}: Read a comment (Comment)
- PATCH /api/v2/comments/{comment}: Edit a comment (Comment)
- GET /api/v2/drive-items/{drive_item}/comments: List a drive item's comments (CommentList)
- POST /api/v2/drive-items/{drive_item}/comments: Post a comment on a drive item (Comment)
- GET /api/v2/work-items/{work_item}/comments: List a work item's comments (CommentList)
- POST /api/v2/work-items/{work_item}/comments: Post a comment on a work item (Comment)

## Comment fields
- 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.

## Variants

### CommentList

What a collection returns, and what `?view=summary` returns on a single record.

11 fields.
Identical to the detail object above.

### CommentSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

5 fields.
Omits: body, commentable_type, commentable_id, commentable, updated_at, links

### CommentLinks

The `links` object on this resource.

Keys: self

## Polymorphic fields
- author: discriminated on `author_type`
- commentable: discriminated on `commentable_type`

## Example
```json
{
  "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"
  }
}
```