Comment ingestion

How it works

A successful POST /api/integrations/posts request resolves a novel, creates or reuses its canonical discussion thread, creates an external identity record, and adds the comment with your integration as its source.

Before account linking, the Forum shows the supplied username with your platform's source label. After the same external UUID is linked, historical and future imported comments resolve to that Genesis account while retaining provenance. Imported comments pass through normal Forum moderation and can be reported or removed; an integration does not receive moderator privileges.

Delivery model

Send one request per source comment, with your immutable source event ID as the Idempotency-Key. Retry delivery failures with the same key; a replay returns the original result instead of duplicating the post. Genesis returns the canonical post and thread IDs so your system can store a cross-reference.

The default limit is 60 imported posts per minute per integration, with JSON payloads below 32 KB. Genesis may approve different throughput after reviewing expected volume and moderation capacity.

Replies

To import a threaded reply, set parent_uuid to the Idempotency-Key you used when delivering the parent comment. Genesis resolves it within your integration and the novel's discussion thread.

Delivery order does not matter: if the parent has not been imported yet, or was never imported, the comment is stored as a top-level post rather than rejected. Check parentPostId in the response to confirm whether the reply attached. Deliver parents before replies when you can.

Novel resolution and metadata

Genesis matches the novel title case-insensitively, first among published Genesis novels, then among approved partner-sourced Forum novels. Send the canonical public title; aliases and approximate matching are not guaranteed. Each novel has one canonical discussion thread that Genesis reuses or creates as part of the comment operation.

If no title matches and your integration has the Create novels capability, Genesis creates a partner-sourced novel; otherwise the request returns novel_not_found. Novels created this way carry only a title, so use POST /api/integrations/novels to create novels with full metadata up front, or to fill in the cover, author, synopsis, genres, language, and reading status later. Genesis-published novels keep their Genesis metadata; the endpoint identifies them as canonical without changing them.

chapterNumber is optional context on a comment, with decimals such as 12.5 supported. It does not create, publish, or unlock a Genesis chapter.

Identity and timestamps

The pair integration + external UUID identifies the imported author; use the same UUID in comment ingestion and account linking, and never recycle one from a deleted account. The username is display metadata, not the identity key: later deliveries may update it without creating a second identity.

Send timestamp when preserving the original publication time matters, as ISO 8601 with an explicit timezone. Genesis stores both the source time and import time; without a source time, receipt time is used. Values more than five minutes in the future are rejected.

Content rules

Do not send HTML, credentials, private messages, or content the user did not intend to publish. The supplied text is handled as Forum comment content and remains subject to automated checks, reports, staff moderation, and applicable retention rules.