Novelist Agentic API

Use this skill when a user asks an agent to browse Novelist books, buy a bookstore novel, generate a custom novel or the next book of a series, download an EPUB or PDF, buy an audiobook, order a printed copy of a book, check generation or shipping status, or review a book programmatically.

Public API base:

https://ainovelist.app/api/agent/v1

Start every session with the free catalogue. It lists the options that are live right now and their current prices:

GET /catalog

Payment Model

• Browsing, the catalogue and print quotes are free and unauthenticated.
• Paid operations accept either x402 over HTTP 402 Payment Required, or an API key backed by prepaid credits.
• x402 currency is USDC. The accepted networks are listed in the payment-required header and in GET /catalog (payment.x402_networks). The wallet address is the agent identity.
• Payer addresses are public on-chain, so reading what a wallet owns (status, downloads, history, purchases, audiobooks, print orders) and reviewing a book with a tx_hash also need a wallet-ownership proof: a short signature of a Novelist message sent in X-Wallet-Signature and X-Wallet-Timestamp. A call without it returns 401 with the exact message_to_sign. Details in PAYMENT.md. API-key callers never need it.
• API keys: the user signs up at https://ainovelist.app, opens the dashboard, creates an API key and adds prepaid credits (EUR). Credits are shared by all keys on the account.
• Novel generation uses deferred settlement (x402) or a credit reservation (prepaid): payment is captured only after the novel is delivered.
• Book purchases, audiobooks and print orders are settled immediately.
• If a server restart interrupts a paid generation, the book resumes automatically and is settled only when it is delivered.

Claude Connector

People chatting with Claude can use the Novelist connector instead of this API: a remote MCP server at https://ainovelist.app/api/mcp that signs in with the user's Novelist account (OAuth). Its tools describe what a novel includes with reference prices (get_novel_options), save a novel brief and return a studio link where the user reviews and pays (prepare_novel, including writer mode briefs while the website offers writer mode), track the user's novels (list_my_novels, get_novel_status), and link a finished novel to the printed-copy page (get_printed_copy_link). The connector never pays or starts a novel. It is packaged with a skill as the novelist Claude plugin in this repository (plugins/novelist). Use this HTTP API when an agent must pay and generate autonomously.

Public Files

• SKILL.md: core workflow and endpoint map.
• GENERATION.md: generation options (tier, size, artwork style, format, language), dedications, character photos, cover direction, saga sequels, status polling and downloads.
• PRINT.md: physical printed copies: quote, order, pay, track, refunds.
• AUDIOBOOK.md: AI-narrated audiobooks: price, buy, narration status, download.
• PAYMENT.md: x402 and prepaid-credit payment details, network constants and safety rules.
• package.json: metadata for agents and catalog tooling.

Endpoint Map

"Owner" means the API key of the account (Authorization: Bearer <api_key>) or, for x402, the wallet parameter plus the wallet-ownership proof headers of that wallet.

Workflows

Browse books

GET /books?page=1&per_page=20
GET /search?q=lighthouse
GET /books/{book_id}

Filters for /books and /search:

Each book carries quality_tier and its own price_usdc. World Class books cost more than Pro books.

Purchase a bookstore novel

GET /books/{book_id}/purchase

1. x402: call without payment, read the payment-required header of the 402 response, sign it, retry with PAYMENT-SIGNATURE.
2. Prepaid credits: call with Authorization: Bearer <api_key> and a unique Idempotency-Key.
3. Read download.epub_url and purchase_id from the response.
4. Buying a book the wallet already owns charges nothing and returns status: already_purchased; with x402 that answer needs the wallet-ownership proof headers.
5. Send one paid request per book at a time. If a paid call times out, do not sign a new payment: retry the same one, or check GET /wallet/{wallet_address}/purchases first. A second purchase of the same book by the same wallet waits for the first one and is then answered as already_purchased without charging.
6. If a second payment still settles for a book the wallet already owns, the call returns 200 with status: duplicate_payment, the existing purchase_id and download, and transaction.refund: manual. Keep the book; the extra payment is refunded by hand, so report the tx_hash to support and do not pay again.

Generate a custom novel

POST /generate

Minimum body:

{
  "title": "The Quantum Garden",
  "synopsis": "A botanist inherits a mysterious garden where plants exist in quantum superposition.",
  "publish_to_bookstore": true
}

Main options (all optional, defaults in GENERATION.md):

Flow:

1. Choose x402 or prepaid credits.
2. x402: call /generate with the body, read the payment-required header, sign it for the same body and retry with PAYMENT-SIGNATURE.
3. Prepaid credits: call /generate with Authorization: Bearer <api_key> and a unique Idempotency-Key.
4. Store the returned request_id.
5. Poll status until completed or failed:
   • x402: GET /status/{request_id}?wallet={wallet_address} with the wallet-ownership proof headers (one proof lasts 300 seconds)
   • prepaid credits: GET /status/{request_id} with Authorization: Bearer <api_key>
6. Download from download.epub_url and/or download.pdf_url before the links expire.
7. x402: keep the purchase_id from the status response; it proves ownership when reviewing the book. A failed generation has a short error code and is not charged.

Read GENERATION.md before generating a novel.

Writer mode (website only)

Writer mode is a World Class novel that its author finishes in the Writer Studio and may publish and sell under the Novelist Writer License, keeping the co-creation credits in every edition. A person must accept that license and finish the book on the website, so this API never sells it: POST /generate with writer_mode: true returns 400 with writer_mode_requires_web_studio, before any quote or payment.

While the website offers writer mode, GET /catalog lists it under writer_mode (available: true) with start_url, landing_url, license_url and reference prices in EUR; otherwise it shows available: false. When a user wants to publish a novel as its author, send them to start_url. With the Claude connector, prepare_novel can prepare a writer mode brief for them to review.

Order a printed copy

Books generated with output_format pdf or both can be printed and shipped (Lulu print on demand). Only the book's owner can order: the wallet that paid for the generation, or the account of the API key.

POST /print/quote
POST /print/orders
GET /print/orders/{order_id}

Read PRINT.md before ordering.

Buy an audiobook

Any completed book the buyer can read (generated, bought, or public in the bookstore) can be narrated in its language.

GET /audiobooks/{book_id}
POST /audiobooks/{book_id}

Read AUDIOBOOK.md before buying.

Review a book

POST /books/{book_id}/agent-score
GET /books/{book_id}/agent-score?purchase_id={purchase_id}
DELETE /books/{book_id}/agent-score?purchase_id={purchase_id}
GET /books/{book_id}/agent-scores

Reviews need proof of ownership with an x402 wallet. Send the purchase_id from the purchase response or, for a book you generated, the purchase_id from GET /status/{request_id}: it works on its own. The generation request_id is also accepted as purchase_id while the book is not published in the bookstore; once it is published, only the status purchase_id works on its own.

A tx_hash is also accepted, but it is public on-chain, so it counts only together with the wallet-ownership proof headers (X-Wallet-Signature, X-Wallet-Timestamp) of the wallet that paid. Without them the call returns 401 with the exact message_to_sign (see PAYMENT.md); a proof from any other wallet is refused. Prefer purchase_id. Scores are 0-10: overall_score (required) plus optional coherence, characters, pacing, voice, originality, continuity, and a comment (max 2000 characters).

Safety Rules

• Never ask the user to paste a private key or seed phrase into chat.
• Never log private keys, payment signatures, API keys or wallet seed phrases.
• Treat PAYMENT-SIGNATURE, X-Wallet-Signature and API keys as secrets. Never put them in URLs, prompts, logs or public repositories.
• Only sign the exact Novelist wallet-ownership proof text (the message_to_sign of a Novelist 401). It is not a payment; never sign anything else in its place.
• Do not invent prices. The payment-required header is authoritative for x402; the catalogue and quotes show current prices.
• Do not reuse payment nonces or stale payment headers.
• Send a unique Idempotency-Key for every paid prepaid-credit call, and reuse the same key only when retrying the same operation.
• A shipping address is personal data. Use only an address the user explicitly gave for this order.
• Do not poll faster than poll_interval_seconds when present.
• If generation fails, tell the user that deferred settlement or the credit reservation means the failed job is not charged.

Public Constants

The live GET /catalog response is authoritative for which networks are currently accepted.

Supported Languages

en, es, fr, de, it, pt, nl, ja, ko, zh, ar, hi, id, ca, eu, sv, no, da, fi, pt-br, pl, zh-tw