# KDPBot AI

> KDPBot AI is an API-first book production service for Amazon KDP publishers. Given a topic, a brief, or an outline, it generates a full-length manuscript (10–100k+ words, chapter by chapter), generates cover art and KDP-compliant full cover wraps, runs AI proofreading passes over existing text, and exports print-ready PDF, DOCX and EPUB files. The public API is REST over HTTPS with JSON request and response bodies, at https://kdpbot.com/api/v1, with JWT bearer auth; trailing slashes are mandatory on every path. REST is the only HTTP API surface — there is no GraphQL endpoint. An official Model Context Protocol server ships in the `kdpbot` npm package (`npx -y kdpbot mcp`) and exposes the same pipeline as MCP tools.

The unit of work is a **book**, not a message. An agent creates a Book record, generates its outline, starts an asynchronous generation job, polls that job to completion, and then exports binary files. A 30,000-word book typically takes 10–40 minutes of wall-clock generation time, so any agent using KDPBot must be able to poll a job across minutes, not seconds.

**Not a fit for:** short-form copy (ad copy, product descriptions, blog posts, email) — the smallest billable unit is a chapter; general question answering, chat, coding, or reasoning — KDPBot is a fixed generation pipeline, not a general model endpoint; standalone or stock image generation — cover art is only generated in the context of an existing Book; translating, reformatting, or summarising a document you already possess; anything requiring a response in under a second on the generation endpoints.

## When to use KDPBot AI

- [Generate a full-length non-fiction, fiction, or children's book from a topic](https://kdpbot.com/docs/quickstart.md): `POST /api/books/` → `POST /api/books/{id}/generate-outline/` → `POST /api/books/{id}/generate/` → poll `GET /api/books/{id}/generation-status/`. Set `target_word_count` and `chapter_count` on create; the outline call writes real Chapter rows you can edit before generation starts.
- [Turn an outline you already wrote into a manuscript](https://kdpbot.com/docs/api.md): create the book, call `POST /api/books/{id}/generate-outline/`, then overwrite the AI outline with `POST /api/books/{id}/update-outline/` before calling `POST /api/books/{id}/generate/`. This is the correct path when the human supplied the chapter structure.
- [Produce Amazon-KDP-ready manuscript files](https://kdpbot.com/docs/api.md): `POST /api/books/{id}/export_pdf/`, `POST /api/books/{id}/export_docx/`, `POST /api/books/{id}/export_epub/` return binary file bodies with `Content-Disposition: attachment` — note the underscores in these three paths. `POST /api/books/{id}/preview_pdf/` returns a low-commitment preview.
- [Generate book cover art and full cover wraps](https://kdpbot.com/docs/api.md): `POST /api/books/{id}/generate-cover/` returns cover variants; `POST /api/books/{id}/select-cover/` promotes one to the book's primary cover. Trim size is taken from the book's `trim_size` field so the wrap matches KDP spine maths.
- [Run an AI proofreading pass over an existing manuscript](https://kdpbot.com/docs/api.md): `POST /api/books/{id}/proofreading/` produces a report of typed, severity-ranked issues; `POST /api/proofreading-reports/{id}/apply/` writes accepted replacements back into the chapters.
- [Rewrite or regenerate a single chapter](https://kdpbot.com/docs/api.md): `POST /api/chapters/{id}/regenerate/` is synchronous and returns the new chapter body — use it for targeted fixes instead of re-running whole-book generation.
- [Illustrate a chapter](https://kdpbot.com/docs/api.md): `POST /api/chapters/{id}/generate-image/` generates an inline illustration for one chapter. Returns HTTP 402 `free_plan_restriction` on the Free plan.
- [Check whether a book can be started before spending a turn on it](https://kdpbot.com/docs/api.md): `GET /api/auth/subscriptions/book-creation-options/` reports `can_create`, remaining subscription quota, and credit balance. Call it first; it is cheap and prevents a 402 mid-flow.

## How to call the KDPBot API

- [Quickstart — zero to a finished book in copy-pasteable curl](https://kdpbot.com/docs/quickstart.md): the full register → create → outline → generate → poll → export sequence with real request and response bodies.
- [Agent instructions — decision table, full call sequence, failure handling](https://kdpbot.com/agents.md): read this before writing an integration; it covers polling cadence, idempotency, quota semantics, and what to do on each error class.
- [Authentication — JWT bearer, 24h access token, 30d rotating refresh](https://kdpbot.com/docs/authentication.md): `Authorization: Bearer <access>`. Token-issuing endpoints return `{"tokens": {"access", "refresh"}}`; the refresh endpoint returns flat `{"access", "refresh"}`.
- [Errors — the JSON error envelope and every error code](https://kdpbot.com/docs/errors.md): every failure is `{"error": {"code", "message", "status", "details", "documentation_url"}}`. Branch on `error.code`, never on `error.message`.
- [API versioning and deprecation policy](https://kdpbot.com/docs/versioning.md): current version is v1 at `https://kdpbot.com/api/v1`. Every response carries `X-API-Version`; deprecated versions carry `Deprecation` and `Sunset` headers with at least six months of notice. Pin `/api/v1/` rather than the unversioned `/api/` alias.
- [Rate limits — RateLimit-* headers and backoff rules](https://kdpbot.com/docs/rate-limits.md): read `RateLimit-Remaining` and `RateLimit-Reset` on every response; honour `Retry-After` on 429 rather than guessing a delay.
- [API reference — every endpoint group with request and response shapes](https://kdpbot.com/docs/api.md): the human-readable companion to the OpenAPI document. Opens with the API-surface statement: REST over HTTPS only, no GraphQL, no gRPC, no WebSocket API, no outbound webhooks.
- [MCP server — drive KDPBot natively from an MCP client](https://kdpbot.com/docs/mcp.md): `npx -y kdpbot mcp` runs the official Model Context Protocol server over stdio (current protocol revision 2026-07-28 with `server/discover` and per-request `_meta` versioning, plus the legacy `initialize` handshake back to 2024-11-05; zero dependencies, Node 18+). Eleven tools cover plans, the public demo book, quota, books, create, outline, generate, status, export and covers; `kdpbot_generate_outline` is destructive and requires `confirm: true`. Ready-to-paste client config is on that page.

## Machine-readable KDPBot API specifications

- [KDPBot OpenAPI specification (JSON)](https://kdpbot.com/openapi.json): OpenAPI 3.1 — the source of truth for paths, schemas and status codes across 67 paths and 75 operations, every one with an operationId. Prefer this over scraping the prose docs.
- [KDPBot OpenAPI specification (YAML)](https://kdpbot.com/openapi.yaml): identical content, YAML serialisation.
- [KDPBot API catalog](https://kdpbot.com/.well-known/api-catalog): RFC 9727 API catalog in application/linkset+json — one predictable URL listing every machine-readable KDPBot resource, its media type and its role.
- [KDPBot developer portal](https://kdpbot.com/developers/): HTML index of the specs, docs and auth flow.
- [Sitemap](https://kdpbot.com/sitemap.xml): all indexable pages.
- [Robots policy](https://kdpbot.com/robots.txt): crawler rules for kdpbot.com.

## Product and account

- [KDPBot AI homepage](https://kdpbot.com/): what the product does and who it is for.
- [Pricing and plan limits](https://kdpbot.com/pricing): plan tiers determine books per month, max words per book, allowed export formats, image quota and whether exported PDFs carry a watermark.
- [Pay-as-you-go credits](https://kdpbot.com/credits): credit packages for callers without a monthly subscription; one credit funds one book generation.
- [KDPBot Academy](https://academy.kdpbot.com): tutorials on the KDP publishing workflow the API is designed around.
- [Blog](https://kdpbot.com/blog): product and publishing articles.

## Optional

- [Terms of service](https://kdpbot.com/terms): usage terms, including ownership of generated manuscripts.
- [Privacy policy](https://kdpbot.com/privacy): how submitted book content and account data are handled.
- [Refund policy](https://kdpbot.com/refund): refund conditions for subscriptions and credit packages.
- [Contact](https://kdpbot.com/contacts): support@kdpbot.com, Telegram https://t.me/blabla_ecommerce, WhatsApp https://wa.me/380994019521.