ColoringBookify

Quick start

Export your API key to an environment variable and verify it against the account endpoint.

Base URL

https://coloringbookify.com/api/v1

export COLORINGBOOKIFY_API_KEY="cbf_your_api_key"

curl --fail-with-body \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  https://coloringbookify.com/api/v1/me

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: page-$(uuidgen)" \
  --data '{"page":{"title":"A fox exploring a mushroom village"}}' \
  https://coloringbookify.com/api/v1/pages

MCP for AI agents

MCP

Use MCP when an AI agent should plan, generate, organize, and download a complete printable coloring book for the signed-in account. Use the REST API for direct application integrations.

MCP server URL

https://coloringbookify.com/mcp

Configure this as a Streamable HTTP server. Compatible clients discover ColoringBookify's OAuth metadata automatically.

Connect with Codex CLI

codex mcp add coloringbookify \
  --url https://coloringbookify.com/mcp
codex mcp login coloringbookify

The browser opens ColoringBookify for sign-in and consent. MCP uses OAuth instead of API keys and requires an active Business plan.

Clients use tools/list to discover the current tool names, input schemas, and descriptions. The catalog covers accounts, print formats, book plans, books, characters, pages, operations, external artwork imports, images, and final PDFs.

Read-only tools cost 0 credits. Generation tools declare their exact cost and require the agent to confirm that amount before spending credits. MCP uses the same account balance as the REST API.

Image and PDF tools return short-lived, owner-authorized download URLs so agents can retrieve binary files without transporting large base64 payloads.

Example request for an agent

Create an 8.5 × 11 inch coloring book about ocean animals. Show me the proposed plan and exact credit cost before generating it, then build the book and download the final PDF.

Authentication

Create one account-level key from the API section in your account, then send it in the Authorization header as a Bearer token. Browser session cookies do not authenticate API requests.

The complete key is shown only after creation or rotation. Store it securely and never put it in URLs, browser-side code, logs, or source control.

Credits and response headers

Every authenticated response reports the balance after the request and the credits actually consumed by that HTTP call. The endpoint table and OpenAPI x-credit-cost field declare costs before use.

X-ColoringBookify-Credits-Available: 247
X-ColoringBookify-Credits-Consumed: 1

An idempotent replay reports zero consumed because it does not charge again, while the operation body retains its original charged amount.

Idea to printable book

Plans remain client-held. This avoids stale server drafts while keeping the user in control before any credit-changing generation.

1. Create a stateless plan with POST /book_plans and display its page concepts and exact credit estimate.
2. Let the user review or edit the returned generation_request, then submit it to POST /books with a new idempotency key.
3. Poll the returned operation until terminal. Import or replace externally repaired artwork when needed.
4. Call GET /print_formats, then download the complete book from GET /books/{id}/pdf.

Generation, retries, and operations

Send a unique Idempotency-Key header with every generation request. Retrying the same method, path, and payload with the same key returns the original response without generating or charging again; reusing it for a different request returns 409.

Generation returns 202 with a resource and an operation. Poll the operation URL until its status is succeeded, partially_succeeded, or failed. Nonterminal responses include Retry-After.

Page aspects and PDF sizes

Call GET /api/v1/print_formats rather than hard-coding sizes. PDF formats must match the book aspect; imported images are normalized without cropping when only a small adjustment is needed.

Book aspect	Recommended image pixels	Recommended PDF formats
square (1:1)	1024 × 1024	square, small_square
portrait (3:4)	1152 × 1536	us_letter, a4
landscape (4:3)	1536 × 1152	us_letter_landscape, a4_landscape

Endpoints

Read, create, update, generate, organize, and remove resources owned by the authenticated account.

Method	Path	Credits	Description
GET	/api/v1/me	0	Get the account plan, credits, and API capabilities.
GET	/api/v1/print_formats	0	List supported PDF sizes, compatible aspects, and recommended image dimensions.
POST	/api/v1/book_plans	0	Create a stateless editable book plan, exact credit estimate, and ready-to-submit generation payload.
GET	/api/v1/operations	0	List asynchronous generation operations for the account.
GET	/api/v1/operations/{id}	0	Poll the current status, progress, and credit result of an operation.
GET	/api/v1/characters	0	List active reusable characters owned by the account.
POST	/api/v1/characters	1	Create and asynchronously generate a reusable character.
GET	/api/v1/characters/{id}	0	Get one owned active reusable character.
PATCH	/api/v1/characters/{id}	0	Update a character's name or public preview setting.
PUT	/api/v1/characters/{id}	0	Update a character's name or public preview setting.
DELETE	/api/v1/characters/{id}	0	Archive an owned reusable character.
GET	/api/v1/characters/{id}/reference_image	0	Download the character's authorized generated reference image.
POST	/api/v1/characters/{id}/regenerate	1	Asynchronously regenerate a reusable character.
POST	/api/v1/characters/{id}/restore	0	Restore an archived reusable character.
GET	/api/v1/books	0	List books owned by the account.
POST	/api/v1/books	1 per generated content page	Create a book and asynchronously generate its pages and cover.
GET	/api/v1/books/{id}	0	Get one owned book with its ordered page summaries.
PATCH	/api/v1/books/{id}	0	Update book metadata and reusable characters.
PUT	/api/v1/books/{id}	0	Update book metadata and reusable characters.
DELETE	/api/v1/books/{id}	0	Delete an owned book.
GET	/api/v1/books/{id}/pdf	0	Generate and download a standard final PDF after every included page is ready.
POST	/api/v1/books/{book_id}/pages	0 attach / 1 generate	Generate a new page or attach an existing ready page to a book.
DELETE	/api/v1/books/{book_id}/pages/{id}	0	Detach a page from a book without deleting the page.
PATCH	/api/v1/books/{id}/pages/order	0	Replace the ordered list of pages in a book.
GET	/api/v1/pages	0	List pages owned by the account.
POST	/api/v1/pages	1	Create and asynchronously generate a standalone page.
POST	/api/v1/pages/import	0	Import finished external artwork as a ready standalone page.
GET	/api/v1/pages/{id}	0	Get one owned page.
PATCH	/api/v1/pages/{id}	0	Update page metadata and reusable characters.
PUT	/api/v1/pages/{id}	0	Update page metadata and reusable characters.
DELETE	/api/v1/pages/{id}	0	Delete an owned page.
GET	/api/v1/pages/{id}/image	0	Download the page's authorized generated image.
PUT	/api/v1/pages/{id}/image	0	Replace a page image with finished external artwork without AI generation.
POST	/api/v1/pages/{id}/regenerate	1	Asynchronously regenerate an owned page.

Pagination

List endpoints accept limit from 1 to 100, defaulting to 25, and an opaque after cursor returned as meta.next_cursor. Treat both resource IDs and cursors as opaque strings.

curl --get https://coloringbookify.com/api/v1/pages \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=next_cursor_value"

Responses and errors

JSON errors use a stable envelope with a machine-readable code, a safe message, and the request ID. Responses include the API version header and are never publicly cached.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "request-id"
  }
}

400

Invalid pagination or request parameters.

401

The Bearer token is missing or invalid.

402

The account does not have enough credits for the generation.

403

The account does not currently have an active Business plan.

404

The resource does not exist or is not owned by the account.

409

The idempotency key conflicts with another request or generation is already active.

422

The request failed validation or an account limit was reached.

429

Too many planning requests were made in a short period.

503

Book planning is temporarily unavailable.

Security and current scope

• All API responses use Cache-Control private, no-store.
• Image downloads recheck ownership on every request.
• Source images and permanent storage URLs are never exposed.
• Provider exception details and internal URLs are omitted from errors.

Generation endpoints require idempotency keys, record append-only credit transactions, and expose only safe operation errors.