Books

Create a book record

Creates a book that covers can be generated against. author is required unless genre is the planner genre (Planner & Journal / planner-journal). When subgenre is omitted for a high-variance genre, the server auto-detects one from the book details (an explicit subgenre always wins; detection failure leaves it null). An explicit subgenre must be one of the genre's values, else 400 invalid_subgenre. Supports idempotent replay via the Idempotency-Key header: a repeated key returns 200 with the previously created book instead of 201.

post/api/v1/books

Request

  • Base URL: https://beyourcover.com
  • URL: https://beyourcover.com/api/v1/books
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional idempotency key. If a resource/job was already created with the same key (scoped to the API key for jobs, to the user for books), the endpoint returns 200 with the existing resource instead of creating a duplicate. Concurrent duplicates are also collapsed via a unique-constraint retry.

Request body

titlestring required

Book title. Required. Rendered on the cover, so Arabic and Hindi/Devanagari scripts are rejected (unsupported_characters).

authorstring

Author name. Required unless genre is Planner & Journal / planner-journal. Same script restrictions as title.

subtitlestring

Optional subtitle. Same script restrictions as title.

genrestring required

Required. Accepts either a kebab-case genre slug (e.g. science-fiction, business-economics, religion-spirituality, non-fiction, fantasy, romance, thriller, mystery, horror, historical-fiction, health-fitness, contemporary-fiction, young-adult, childrens, self-help, biography-memoir, poetry, planner-journal, other) or the canonical genre value (e.g. Science Fiction). Unrecognized values return invalid_genre.

subgenrestring

Optional subgenre value. Must be one of the genre's values, exactly as written (see GET /api/v1/capabilities, genres[].subgenres[].value). Any other value returns invalid_subgenre, and the message lists the valid values. A genre with no subgenres (other) takes none. If omitted for genres that have subgenres, the server auto-detects one.

summarystring

Optional plot/content summary used to inform generation.

target_audience'children' | 'middle-grade' | 'young-adult' | 'new-adult' | 'adult'

Optional. Must be one of the predefined audience values.

external_refstring

Optional caller-supplied reference. Echoed back in the response (not stored on the book).

planner_yearstring

Optional. Only meaningful for the planner genre. Must be a string if provided (type-checked; no length limit is enforced in code).

Response

Idempotent replay: a book with the same Idempotency-Key already exists for this user. external_ref is echoed from the current request, not the original one.

bookIdstring uuid required
subgenrestring nullable required

The stored subgenre: the caller-provided value, an auto-detected one, or null.

external_refstring nullable required

Echo of the request's external_ref (not persisted on the book).

created_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.