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 — in verify mode body.user_id is ignored, and the user is created on their first action.
• Pass Idempotency-Key: <uuid> for retry-safe posting.

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_content — 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.