Create a comment with forged author + optional created_at

POST

/admin/seed/comments

• Local development behind nginx (port 8088 by default)

Operator-tooling endpoint for the demo-seed loader. NOT for general operator use — gated on system.admin; not surfaced in the admin UI.

Creates a single comment with author_user_ref forged to the supplied user (the regular POST /posts/{id}/comments stamps the caller as author, which is wrong for seeding per-post reviewer voices).

Idempotent when the caller supplies a stable id: a re-run with the same id returns 200 with the existing row instead of 409 — apply scripts can re-run safely.

Emits one admin.seed.comment_created audit per call.

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

object

id

Optional stable UUID for idempotent re-runs. When omitted the server generates one.

string format: uuid

nullable

target_kind

required

string

Allowed values: post asset collection

target_id

required

string format: uuid

author_user_ref

required

Forged author. Must reference an existing user.ref. The seed loader uses this to attribute comments to per-post reviewer voices distinct from the operator running apply.

integer format: int64

parent_id

Optional parent comment. When set, depth + root_id are derived from the parent (same logic as the public CreateComment path).

string format: uuid

nullable

body

required

string

>= 1 characters

body_html

Defaults to empty (matches the local CreateComment path; the frontend renders body directly with whitespace-pre-wrap).

string

nullable

annotation_type

string

nullable

Allowed values: point rect timestamp frame whiteboard text-range

annotation_data

object

key

additional properties

any

created_at

Optional creation timestamp. Defaults to NOW() when omitted. The seed loader uses this to align comment timeline with the 14-month interlaced feed.

string format: date-time

nullable

Responses

200

Idempotent re-run — the supplied id already exists; the existing row is returned unchanged.

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

201

Comment created.

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

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

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

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Either the target object (post / asset / collection) or the supplied author user does not exist.

object

error

required

Human-readable error summary

string

Example

the request could not be completed