API Documentation

Integrate coloring page generation into your apps with our REST API

Authentication

The API is currently open and does not require authentication. Rate limiting applies at 60 requests per minute per IP address.

Endpoints

POST/api/generate

Generate a new coloring page. The image is automatically saved, categorized, and made available in the gallery.

Request Body

{
  "prompt": "A friendly dragon reading a book",
  "size": "letter"  // "letter" | "a4" | "square" (default: "letter")
}

Response

{
  "id": "uuid",
  "prompt": "A friendly dragon reading a book",
  "imageUrl": "https://...supabase.co/storage/.../original.png",
  "thumbnailUrl": "https://...supabase.co/storage/.../thumb.webp",
  "category": { "id": "uuid", "name": "Fantasy", "slug": "fantasy" },
  "tags": ["dragon", "reading", "book", "friendly"],
  "ageRange": "kids",
  "complexity": "medium",
  "sizePreset": "letter",
  "widthPx": 2550,
  "heightPx": 3300
}

Example (curl)

curl -X POST https://colorcraft.app/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A happy unicorn","size":"letter"}'

Example (Python)

import requests

response = requests.post(
    "https://colorcraft.app/api/generate",
    json={"prompt": "A happy unicorn", "size": "letter"}
)
data = response.json()
print(data["imageUrl"])

Example (JavaScript)

const res = await fetch("https://colorcraft.app/api/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "A happy unicorn", size: "letter" })
});

const data = await res.json();
console.log(data.imageUrl);
GET/api/download

Download a coloring page in any supported format.

Query Parameters

id      - UUID of the coloring (required)
format  - "png" | "jpg" | "pdf" | "svg" (required)
width   - Custom width in pixels (optional)
height  - Custom height in pixels (optional)

Example

curl "https://colorcraft.app/api/download?id=UUID&format=pdf" -o coloring.pdf
GET/api/search

Semantic search across all coloring pages using AI embeddings.

Query Parameters

q     - Search query (required)
page  - Page number (default: 1)
limit - Results per page, max 50 (default: 20)

Example

curl "https://colorcraft.app/api/search?q=dragon&limit=10"
GET/api/gallery

Paginated list of all coloring pages, with optional category filter.

Query Parameters

page     - Page number (default: 1)
limit    - Results per page, max 50 (default: 20)
category - Category slug filter (optional)

Example

curl "https://colorcraft.app/api/gallery?page=1&limit=20&category=animals"
GET/api/stats

Aggregated stats — total colorings, downloads, categories, and top content.

Rate Limiting

All API endpoints are rate-limited to 60 requests per minute per IP. When exceeded, a 429 response is returned. Check the X-RateLimit-Remaining header for your current allowance.