Create or update a novel

Upserts a partner-sourced novel with its cover, author, synopsis, and reading metadata.

POST/api/integrations/novels

Upserts a novel keyed by its case-insensitive title: an unknown title creates a partner-sourced novel, a title your integration already created has its supplied fields updated, and omitted fields are left unchanged. Replaying a request is safe.

Genesis-published novels keep their Genesis metadata; the endpoint identifies them as canonical without changing them. Requires a Bearer API key, Content-Type: application/json, an Idempotency-Key header, and the Create novels capability. Maximum request size: 32 KB.

Parameters

novelstringRequired

Canonical novel title, 1–300 characters. This is the upsert key and cannot be changed afterwards.

authorstringOptional

Author name, 1–120 characters. Defaults to Unknown on creation.

synopsisstringOptional

Plain-text synopsis, at most 5,000 characters.

coverUrlstringOptional

https URL of the cover image, at most 2,000 characters. Must be stable and publicly reachable; Genesis renders it directly.

genresstring[]Optional

Free-text genres, at most 20 entries of 1–50 characters each. Replaces the stored list when provided.

languagestringOptional

Original language, at most 50 characters, such as ko.

readingStatusstringOptional

One of ongoing, completed, or hiatus.

Returns

Returns 201 Created when a new partner-sourced novel is created. 200 OK means the title already existed: updated: true when your integration's novel absorbed the supplied fields, canonical: true when the title matched a Genesis-published novel, and both false when the title belongs to a novel your integration does not own.

Every response includes novelId, slug, and the public url so you can store a cross-reference.

Errors

novel_rejected

Genesis staff declined this title; it cannot be reimported.

capability_disabled

The integration does not have Create novels enabled.

rate_limited

The per-minute creation limit was exceeded. Retry after a pause.

invalid_idempotency_key

The Idempotency-Key header is missing or malformed.

invalid_request

A field failed validation; the message names it.

See Errors for shared statuses and retry guidance.

POST /api/integrations/novels

curl https://forum.genesistudio.com/api/integrations/novels \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: novel-45217-v3" \
  -d '{
    "novel": "Memorize",
    "author": "Ro Yu-jin",
    "coverUrl": "https://cdn.example.com/covers/memorize.webp",
    "synopsis": "A returnee restarts the tower with every memory intact.",
    "genres": ["Action", "Fantasy"],
    "language": "ko",
    "readingStatus": "ongoing"
  }'

Response · 201 Created

{
  "created": true,
  "updated": false,
  "canonical": false,
  "novelId": "b7c3f7d0-2f6a-4f4e-9dc0-6a1f0c9e2b41",
  "slug": "memorize-3f9a1c",
  "url": "https://forum.genesistudio.com/novels/memorize-3f9a1c"
}