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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’s id.
Query Parameters
Section titled “Query Parameters ”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.
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.
Responses
Section titled “ Responses ”A page of threads, each with all of its comments.
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
The local user who wrote the comment. Left out for comments received from another instance.
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.
object
The paired instance a received comment came from. Left out for comments written on this instance.
The author’s address on their home instance, for example https://studio-b.example/users/bob. Left out for comments written on this instance.
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.
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.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completed