Comments & discussions

A discussion is a thread of comments scoped to one piece of your content. Discussions are lazy: you never create one explicitly — it materialises when the first comment is posted, keyed by your content identifier (the external id).

In practice, you address comments by your own article id rather than an RSMG Engage UUID.

Post a comment

POST /api/v1/discussions/by-external/{externalId}/comments
X-API-Key: ek_…
X-RSMG-Engage-Identity: <assertion>
X-RSMG-Engage-Identity-Signature: t=…,v1=…,kid=…
Content-Type: application/json

{ "body": "Great match!", "parent_id": "<uuid, optional, for replies>" }

• The first post for an externalId creates the discussion (its title defaults to the externalId).
• The acting user comes from the identity assertion — you don't send a user_id; the user is created on their first action.
• Pass Idempotency-Key: <uuid> for retry-safe posting.

Moderation can hold a comment

The 201 response's status field can be published, pending, or hidden — word filters and the moderation pipeline decide. pending and hidden comments don't appear in list reads and emit no SSE event; if a held comment is later approved, a comment_approved SSE event signals publication. Check status before rendering the new comment optimistically.

Read comments

GET /api/v1/discussions/by-external/{externalId}/comments?limit=20&sort=newest
X-API-Key: ek_…

• Returns 404 before the first comment exists (the discussion isn't materialised yet) — this is normal; render an empty state.
• Results are cursor-paginated: pass the returned cursor as ?cursor=…, and trust the response's hasMore flag.
• Pass the viewer's identity assertion to enrich each comment with viewer-specific fields, such as whether they've reacted.

Edit and delete

Action	Endpoint	Notes
Edit	PATCH /api/v1/comments/{commentId}	Author-only; allowed within the tenant's edit window.
Delete	DELETE /api/v1/comments/{commentId}	Author self-delete; soft-delete (thread stays coherent).
Report	POST /api/v1/comments/{commentId}/report	One report per reader per comment.

All three carry the identity assertion, so RSMG Engage verifies the acting reader as the author or reporter.

Discussion lifecycle

An admin — or a key with moderate_discussion — can lock, unlock, or archive a discussion, for example to close comments when an article is retired. Writes to a locked discussion return 403 DISCUSSION_LOCKED — see Errors.

The exact request and response schema for every field is in the API Reference under Comments and Discussions.