List the comment thread on a post

GET

/posts/{id}/comments

• Local development behind nginx (port 8088 by default)

Returns LIVE comments (deleted_at IS NULL), grouped by root, within each root sorted depth-then-time so replies appear under their parent. Threads ordered newest-root-first. Cursor pagination advances by root.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Query Parameters

limit

integer

default: 50 >= 1 <= 200

cursor

string

Responses

200

A page of comments

object

items

required

Array<object>

A single comment in a thread. Threading is via parent_id + root_id + depth (caller renders nested replies indented by depth). annotation_* fields are NULL for plain comments; the review-mode feature reuses the same row shape.

Federation: exactly one of {author_user_ref} XOR {peer_id + actor_uri} is set per row. Local-authored comments have author_user_ref set + peer_id NULL. Remote-authored comments (from a paired peer per ADR 0043 / phase 1.22.D) have author_user_ref NULL + peer_id + actor_uri + display_name populated. Clients render “<display_name> @ <peer’s host>” for remote rows.

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

Local author user.ref. NULL for remote-authored comments (see peer_id / actor_uri).

integer format: int64

nullable

body

required

string

body_html

required

Server-rendered safe HTML; clients should render this rather than reformatting body.

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 federation peer that originated this comment. NULL for local-authored rows. Set in tandem with actor_uri

• display_name when the comment came in via the federation inbox.

string format: uuid

nullable

actor_uri

The remote actor’s URI on their home instance (e.g. https://studio-b.example/users/bob). NULL for local-authored rows.

string

nullable

display_name

Display name resolved from federation_remote_actors cache for remote-authored comments. May be empty if the remote instance hasn’t shipped display hints yet; clients should fall back to the actor_uri’s host + local-part when this is empty.

string

nullable

next_cursor

string

nullable

401

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"
}

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed