Built&Written Agent API
Agent API reference
Use the Agent API when an external agent, IDE, or custom workflow needs a fixed Bearer token instead of the OAuth-based MCP connector. For Claude and most MCP clients, start with the guided MCP setup.
https://www.builtwritten.comAuthorization: Bearer <token>Core endpoints
/api/v1/agent/booksList books available to the authenticated account.
/api/v1/agent/booksCreate a new book project from a title, author, and source brief.
/api/v1/agent/books/{bookId}Inspect book status, structure, sharing state, and export readiness.
/api/v1/agent/books/{bookId}/generateStart full-book generation as a background job.
/api/v1/agent/jobs/{jobId}Check the progress of a long-running generation or export job.
/api/v1/agent/books/{bookId}/exports/pdfGenerate a KDP-ready PDF export for a completed book.
/api/v1/agent/books/{bookId}/shareEnable or disable a public share link for a completed book.
/api/v1/agent/books/{bookId}/store-listingRead the store listing of a book: status, what is missing, and the link where the author sends it to review (read scope).
/api/v1/agent/books/{bookId}/store-listingCreate or edit the draft store listing of a book; never submits it (store:write scope, Author plan).
/api/v1/agent/store/listingsList the author's store listings (read scope).
Credits
AI calls through the Agent API and MCP spend credits from the same wallet as the web app, at the same prices. Reading, editing and exporting are free.
Balance headers
Every response that made an AI call, or was refused for credits, carries X-Credits-Charged (credits this request spent) and X-Credits-Balance (credits available after it). If a charge had not landed when the response was sent, both are left out and X-Credits-Pending: true is sent instead; the charge still happens, and the next response shows the balance.
Out of credits
HTTP 402 with error.code CREDITS_EXHAUSTED; error.details has balance, renews_at (when the plan's credits renew) and packs_url (where to buy a credit pack). Retrying does not help.
Per-key budget
An API key may have a monthly credit budget, set on the API keys page. It counts the key's AI calls and the books it started (what each book cost this month). When the key has spent it this calendar month (UTC), AI requests answer 402 KEY_BUDGET_EXHAUSTED with budget, spent, resets_at and settings_url, even while the wallet has credits.
Idempotency-Key
Send Idempotency-Key (1 to 255 visible ASCII characters) on a POST, PUT, PATCH or DELETE to make a retry safe: the same key with the same request returns the stored response (Idempotent-Replayed: true) and charges nothing, for 24 hours. A stored error is replayed as final (retryable: false, reason idempotency_replayed_error): use a new Idempotency-Key to try again. The same key with a different request is 422; while the first request still runs, 409 CONFLICT (retry shortly). POST /api/v1/agent/books keeps its own rule: a UUID key returns the book the first call made.
Books
POST /books/{bookId}/generate holds the book's upper estimate and answers credits_estimate { typical, upper }; the book is charged what it actually used when it finishes, and the rest goes back. model (wren, wren-pro, wren-max) and effort (low, medium, high) are checked against the plan.