Comment on a post, or reply to a comment
POST /posts/{id}/comments
Adds a comment to the post. Leave out parent_id for a top-level
comment, or set it to reply to a comment on the same post; the
server works out the reply’s thread and depth from that comment. The
new comment is returned as saved.
A request body that isn’t valid JSON, or that gives a field a value
of the wrong type, is refused with 400 before anything else is
checked. Then you need to be signed in (401) and hold
posts.comment (part of the Base role) or system.admin (403).
body must contain more than white space (400), and it’s stored
with the surrounding white space trimmed. You then need to be able
to read the post: it’s the same read check GET /posts/{id} makes,
without the mature settings, and a post you can’t read answers 404,
as one that doesn’t exist or is deleted does. A parent_id that
doesn’t exist is 404 and one on another post is 400. A reply to a
deleted comment is accepted, but if that comment started its thread,
the reply won’t show in the thread listing.
Last comes the post’s own setting. If comments_enabled is false,
the answer is 409 with error set to comments_disabled, for
replies too, and nothing from the request is saved; system.admin
doesn’t get past this. The setting is read under a lock on the post
in the same transaction as the insert, so once turning comments off
has been saved, no comment can slip in behind it.
The comment and its activity are saved together. After that, the
server tries to give the post’s author an in-app notice. For a
reply, it also tries the author of the comment it answers, unless
that’s the post’s author, the comment came from another instance or
it has been deleted. For both top-level comments and replies, it
also tries the local users you @-mention by username. You aren’t
notified of your own comment. Blocks and each recipient’s in-app
settings apply, and failures are only logged. Notices aren’t
emailed. Sending the same request twice saves two comments.
body_html comes back empty: the body isn’t turned into HTML.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’s id.
Request Body required
Section titled “Request Body required ”object
The comment’s text, as plain text. It must contain more than white space, and it’s stored trimmed.
The comment you’re replying to, which must be on the same post.
Leave it out or send null for a top-level comment.
Responses
Section titled “ Responses ”The comment as saved.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication 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"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedThe post doesn’t take comments. error is comments_disabled, and
nothing from the request was saved. A client still showing a
composer from an older copy of the post can hide it.
object
Human-readable error summary
Example
the request could not be completed