Skip to content

List a post's comments

GET
/posts/{id}/comments

Returns the post’s comments a page of threads at a time. A thread is a top-level comment with all of its replies, and limit counts threads, not comments, so a page can hold many more comments than limit.

Threads come newest first. Within a thread the top-level comment comes first, then all replies one level down, then all replies two levels down, and so on, each level oldest first. A reply therefore isn’t always placed right after the comment it answers: use parent_id and depth to nest them. Sketches saved on the post are top-level comments too, so they appear here as threads with their replies.

Deleted comments are left out. If a thread’s top-level comment has been deleted, the whole thread is left out, replies included. A reply whose own parent was deleted is still listed, so its parent_id can name a comment that isn’t in the list.

You need to be signed in and able to read the post. That’s the same read check GET /posts/{id} makes, without the mature settings, but here a post you can’t read answers 404, as one that doesn’t exist or is deleted does. No capability is needed, and nothing else filters the comments: anyone who can read the post gets all of them, and blocking someone doesn’t hide their comments.

id
required
string format: uuid

The post’s id.

limit
integer
default: 50 >= 1 <= 200

How many threads to return; 50 when you leave it out. Values below 1 count as 1 and values above 200 as 200, and a value that isn’t a whole number is refused with 400. Each thread comes with all of its replies.

cursor
string

The next_cursor from the previous page, for the threads started before it. A cursor that can’t be read is ignored and you get the first page.

A page of threads, each with all of its comments.

object
items
required
Array<object>

One comment. A reply has parent_id; root_id is the first comment in its thread and depth counts how far down the thread it is (0 for a top-level comment). Annotations also carry annotation_type and annotation_data.

A comment written on this instance has author_user_ref; one received from a paired instance has peer_id and actor_uri instead. Fields with no value are left out.

object
id
required
string format: uuid
target_kind
required
string
Allowed values: post asset collection
target_id
required
string format: uuid
parent_id
string format: uuid
nullable
root_id
required
string format: uuid
depth
required
integer
author_user_ref

The local user who wrote the comment. Left out for comments received from another instance.

integer format: int64
nullable
body
required
string
body_html
required

Normally an empty string: no endpoint except the seed endpoint stores HTML here, comments from other instances don’t carry any, and the web app shows body as plain text. The seed endpoint stores its value unchecked, so don’t display this field as HTML.

string
annotation_type
string
nullable
Allowed values: point rect timestamp frame whiteboard text-range
annotation_data
object
key
additional properties
any
like_count
required
integer format: int64
edited_at
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
peer_id

The paired instance a received comment came from. Left out for comments written on this instance.

string format: uuid
nullable
actor_uri

The author’s address on their home instance, for example https://studio-b.example/users/bob. Left out for comments written on this instance.

string
nullable
display_name

The remote author’s display name. It’s often left out, even for received comments; when it is, show the host and user name from actor_uri instead.

string
nullable
next_cursor

Pass this as cursor to get the next page. It’s there when the server found at least one thread beyond this page and left out when it found none. The next page holds the threads started before the moment this page’s last thread was started, so a thread started at exactly that moment is skipped, and the next page can then be empty.

string
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed