# Comments

Review through comments: open and reply in discussions on a page or block, and update or delete the connection's own comments.

Comments let an agent work beside people in a workspace: ask for a review, answer in a discussion and clean up its own notes. The `notion_review_thread` scenario holds a Launch Checklist page with two open discussions, so the block below loads it first:

```bash
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"notion_review_thread"}'
curl -s "$RYSTIC_URL/v1/comments?block_id=f6000000-0000-4000-8000-000000000101" -H 'Authorization: Bearer secret_placeholder' -H 'Notion-Version: 2026-03-11' | jq -c '.results[] | {id, text: .rich_text[0].plain_text}'
# -> {"id":"f6000000-0000-4000-8000-000000000701","text":"Ready for review: every launch task is done or booked."}
# -> {"id":"f6000000-0000-4000-8000-000000000702","text":"@Review Bot"}
curl -s "$RYSTIC_URL/v1/comments" -H 'Authorization: Bearer secret_placeholder' -H 'Notion-Version: 2026-03-11' -H 'Content-Type: application/json' -d '{"discussion_id":"f6000000-0000-4000-8000-000000000601","markdown":"Reviewed: **ship it**"}' | jq -c '{id, discussion_id}'
# -> {"id":"925e28d1-dad3-4fd4-8000-000000000001","discussion_id":"f6000000-0000-4000-8000-000000000601"}
curl -s -X PATCH "$RYSTIC_URL/v1/comments/f6000000-0000-4000-8000-000000000701" -H 'Authorization: Bearer secret_placeholder' -H 'Notion-Version: 2026-03-11' -H 'Content-Type: application/json' -d '{"markdown":"Ready for review: all launch tasks are done."}' | jq -c '{id, text: .rich_text[0].plain_text}'
# -> {"id":"f6000000-0000-4000-8000-000000000701","text":"Ready for review: all launch tasks are done."}
curl -s -X PATCH "$RYSTIC_URL/v1/comments/f6000000-0000-4000-8000-000000000702" -H 'Authorization: Bearer secret_placeholder' -H 'Notion-Version: 2026-03-11' -H 'Content-Type: application/json' -d '{"markdown":"Edited"}' | jq -c '{status, code}'
# -> {"status":404,"code":"object_not_found"}
curl -s -X DELETE "$RYSTIC_URL/v1/comments/f6000000-0000-4000-8000-000000000701" -H 'Authorization: Bearer secret_placeholder' -H 'Notion-Version: 2026-03-11' | jq -c '{id, original_content_deleted, rich_text}'
# -> {"id":"f6000000-0000-4000-8000-000000000701","original_content_deleted":true,"rich_text":[]}
```

### Creating and listing

`POST /v1/comments` adds a comment in one of three places, with its body as `rich_text` or as `markdown`:

- on a page, named in `parent.page_id`;
- on a whole block, named in `parent.block_id`;
- as a reply in an existing discussion, named in `discussion_id`.

Neither Notion's API nor the simulator opens a discussion on a selection of text inside a block.

`GET /v1/comments?block_id=<page or block id>` lists that page's or block's open comments, oldest first, paged as [Pagination](https://www.rystic.ai/docs/simulators/notion.md#pagination) describes. A block's comments list apart from its page's.

### Updating and deleting

`GET`, `PATCH` and `DELETE /v1/comments/{comment_id}` read, rewrite and delete one comment. A connection can update or delete only a comment it created. Updating or deleting another user's or another connection's comment returns 404 `object_not_found` and leaves the comment as it was.

Deleting a comment is soft, as on Notion. The response and the stored comment carry `original_content_deleted: true` and `rich_text: []`. After that:

| Request on the deleted comment | The simulator |
|---|---|
| `GET /v1/comments/{comment_id}` | returns it with those values |
| `GET /v1/comments` | leaves it out of the list |
| `PATCH` or a second `DELETE` | returns 404 `object_not_found` |

### Times

A comment's `created_time` and `last_edited_time` are rounded down to the minute, as a page's are.

---

Source: https://www.rystic.ai/docs/simulators/notion/features/comments · Markdown: https://www.rystic.ai/docs/simulators/notion/features/comments.md