Simulators

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:

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 with page_size and start_cursor. 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.