# ebookdone — API instructions for AI agents

ebookdone (https://ebookdone.com) turns a book idea into a finished,
publish-ready book: outline, full chapters, cover art, KDP metadata, and
export files (print PDF, cover wrap, ebook PDF, EPUB, DOCX).

You are driving the JSON API on behalf of a user. Everything below is the
complete flow; no other endpoints are needed.

## Setup

- Base URL: https://ebookdone.com/api
- Auth: every request sends the header `Authorization: Bearer <key>`.
  The user creates a key at https://ebookdone.com/account (starts with `ebk_`).
- All request/response bodies are JSON.
- Costs: generating a full book spends 1 credit from the user's balance.
  Ask the user before spending credits. Credits are bought at
  https://ebookdone.com/buy. Without a credit you can still generate
  chapter 1 and a watermarked preview for free (2 draft books max).

## Flow (one book)

1. Create the book:
   POST /books
   {"topic": "<the user's idea, 1-3 sentences, in their words>",
    "audience": "<who it's for>",            // optional but improves quality
    "tone": "<e.g. practical, friendly>",    // optional
    "language": "English",                   // optional, default auto-detect
    "authorName": "<user's author name>"}    // required before full generation
   -> {"id": "<bookId>"}

2. Generate the outline (takes ~30-60s, synchronous):
   POST /books/{id}/outline
   -> {"outline": {"chapters": [{"title", "beats", "target_words"}, ...]}}

3. Review the outline with the user, edit it as needed, then save:
   PUT /books/{id}/outline
   {"outline": <the outline, edited>,
    "title": "<exact title>",        // optional override
    "subtitle": "<exact subtitle>",  // optional
    "authorName": "<author name>"}

4. Write the full book (asynchronous, typically 10-30 minutes):
   POST /books/{id}/generate
   {"unlock": true}     // spends 1 credit the first time; get user consent
   -> {"jobId": "...", "mode": "full"}

5. Generate cover options (asynchronous), then select one:
   POST /books/{id}/covers
   GET /books/{id}/covers
   -> {"covers": [{"id", "selected", "imageUrl"}, ...]}   // empty until the job finishes
   POST /books/{id}/covers/{coverId}/select
   Exports use the selected cover. Let the user pick (show them the
   imageUrls, or the book page at https://ebookdone.com/book/{id})
   unless they asked you to choose.

6. Poll progress every 30-60s (do not poll faster):
   GET /books/{id}/status
   -> {"status": "generating"|"ready"|"failed",
       "chapters": [...], "job": {"pct", "msg", "error"}}
   Stop when status is "ready" (or "failed" — report the job error).

7. Build the publishing files, then download them:
   POST /books/{id}/export
   {"kinds": ["pdf_print", "pdf_cover_wrap", "pdf_ebook", "epub", "docx"]}
   GET /books/{id}/download/{kind}      // streams the file once built
   The KDP metadata pack (description, keywords, categories, pricing
   suggestions) regenerates automatically with every full export and is
   shown on the book page.

Other: GET /books lists the user's books.

## Suggesting the next books from KDP sales data

If the user gives you their KDP dashboard report (.xlsx exported from
https://kdp.amazon.com/en_US/reports-new):

   POST /title-ideas?count=10
   Content-Type: application/octet-stream   // required for scripted calls;
                                            // body: the raw .xlsx bytes
   -> {"performance": [{"title", "paidUnits", "kenpPages", "royaltyUsd"}, ...],
       "analysis": "...",
       "suggestions": [{"title", "subtitle", "topic", "audience", "tone", "rationale"}, ...]}

Each suggestion's topic/audience/tone can be POSTed to /books directly
(step 1 of the flow) to start that book. Show the user the suggestions
and let them pick before creating books or spending credits.

## Rules

- Rate limits: at most 10 book creations and 20 outlines per hour per
  account. Space out polling. Do not retry failed generation in a loop —
  report the error to the user instead.
- Never invent credits, prices, or capabilities not listed here.
- Amazon KDP requires disclosing AI-generated content when publishing;
  remind the user (see https://ebookdone.com/tools/kdp-ai-disclosure).
- The book belongs to the user's account; they review and publish it
  themselves. Do not publish anywhere on their behalf.