Skip to main content

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.

Base URL
https://www.builtwritten.com
Authentication
Authorization: Bearer <token>

Core endpoints

GET
/api/v1/agent/books

List books available to the authenticated account.

POST
/api/v1/agent/books

Create a new book project from a title, author, and source brief.

GET
/api/v1/agent/books/{bookId}

Inspect book status, structure, sharing state, and export readiness.

POST
/api/v1/agent/books/{bookId}/generate

Start full-book generation as a background job.

GET
/api/v1/agent/jobs/{jobId}

Check the progress of a long-running generation or export job.

POST
/api/v1/agent/books/{bookId}/exports/pdf

Generate a KDP-ready PDF export for a completed book.

POST
/api/v1/agent/books/{bookId}/share

Enable or disable a public share link for a completed book.

GET
/api/v1/agent/books/{bookId}/store-listing

Read the store listing of a book: status, what is missing, and the link where the author sends it to review (read scope).

POST
/api/v1/agent/books/{bookId}/store-listing

Create or edit the draft store listing of a book; never submits it (store:write scope, Author plan).

GET
/api/v1/agent/store/listings

List 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.