ColoringBookify API

Quick start

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

Base URL

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

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.

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.

Endpoints

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

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.