API documentation
Create whitepage sites, follow their progress and download the files from your own code, from a no-code tool, or by simply asking an AI assistant. Every request is JSON over HTTPS.
How it works
Three steps, however you connect:
- Create an API key Sign in, open API keys in the dashboard and create a key. It works like a password for your account, so keep it private.
- Ask for a site Send a title and a language, and if you like the topic, audience and keywords. The generation price is taken from your balance and the site starts building.
- Collect your site It is usually ready within minutes. Check its status, or let us call your URL when it finishes, then preview, edit and download the files.
Choose how you connect
- I use an AI assistant Claude, ChatGPT, Cursor and others can create and track sites for you.
- I write code Three REST calls, with curl, PHP, Node.js and Python examples.
- I use a no-code tool Anything that can send an HTTP request, such as Zapier, Make or n8n, can run the same three calls.
No-code tools: anything that can send an HTTP request (Zapier, Make, n8n, a spreadsheet script) can run the same calls. POST /sites starts a site; GET /sites/{uuid} on a timer, or a callback_url, tells you when it is done. Put the API key in the Authorization header.
Key terms
- Site
- One generated website with all its pages. It is identified by a uuid.
- Status
- pending while it builds, done when it is ready, error if it failed. A failed site is refunded automatically.
- API key
- A secret string that proves a request comes from your account. Create and revoke keys in the dashboard.
- Balance
- Prepaid money in your account. Creating a site reserves the generation price from it.
- Callback
- A URL of yours that we call once when a site finishes, so you do not have to keep checking.
- Idempotency key
- A label you attach to a request so that sending it twice never creates, or charges for, two sites.
Use it with AI assistants
Connect an AI assistant and simply ask: "Make a site for my dental clinic, in Turkish." The assistant calls the same API under your account. You stay in control: creating a site costs balance, and good assistants ask you before they do it.
Things you can say
- How much balance do I have, and what does one site cost?
- Which design kits suit a bakery?
- Create a one-page site for Alder House, a quiet harbour guesthouse, in English.
- Is my site ready? Send me the preview link.
Connect over MCP (Claude, Cursor and more)
MCP is the open standard assistants use to call outside tools. Point your assistant at the MCP URL and give it your API key as a Bearer token.
Claude Code
bash
claude mcp add --transport http whitepagekit https://whitepagekit.com/api/v1/mcp \
--header "Authorization: Bearer YOUR_API_KEY"Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"whitepagekit": {
"url": "https://whitepagekit.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:WPK_API_KEY}"
}
}
}
}Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"whitepagekit": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://whitepagekit.com/api/v1/mcp",
"--header", "Authorization:${WPK_AUTH}"],
"env": { "WPK_AUTH": "Bearer YOUR_API_KEY" }
}
}
}Raw JSON-RPC
curl
curl -X POST https://whitepagekit.com/api/v1/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'Claude Desktop reaches remote servers through the mcp-remote bridge, which needs Node.js.
ChatGPT (custom GPT)
- In ChatGPT create a GPT, open Configure and choose Create new action.
- Choose Import from URL and paste https://whitepagekit.com/api/v1/openapi.json?profile=assistant. This trimmed schema holds only the six assistant tools.
- Under Authentication choose API key, set Auth Type to Bearer and paste your API key.
- ChatGPT asks you to confirm requests that change something, so you stay in control of anything that costs balance.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantOpenAI API (MCP tool)
The Responses API can use the MCP URL as a remote tool. require_approval keeps a human in the loop.
Python
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="YOUR_MODEL",
tools=[{
"type": "mcp",
"server_label": "whitepagekit",
"server_url": "https://whitepagekit.com/api/v1/mcp",
"headers": {"Authorization": "Bearer YOUR_API_KEY"},
"require_approval": "always",
}],
input="What does one site cost, and which design kits suit a bakery?",
)
print(response.output_text)Your own tool loop (function calling)
If you run the model loop yourself, fetch ready-made tool schemas and run each tool call against the matching REST endpoint. Formats: openai (Responses API), openai-chat, anthropic and mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcpThe six tools
| Tool | What it does | REST call | Cost |
|---|---|---|---|
get_account |
Shows your balance and what one site costs. | GET /me |
Free |
list_languages |
Lists the languages a site can be written in. | GET /languages |
Free |
list_themes |
Searches the design kits by topic or style. | GET /themes |
Free |
create_site |
Starts generating a site and takes the generation price from your balance. | POST /sites |
Uses balance |
get_site |
Shows one site: progress, preview link and download link. | GET /sites/{uuid} |
Free |
list_sites |
Lists your sites, newest first. | GET /sites |
Free |
Give any AI these docs
This page is also available as plain Markdown, ideal for pasting into a chat or handing to a coding assistant:
Markdown
https://whitepagekit.com/api/v1/docs.mdA prompt you can paste
Prompt
You can build websites with the White Page Kit API. Read https://whitepagekit.com/api/v1/docs.md first.
My API key is in the environment variable WPK_API_KEY.
Check my balance and the price, then create a site for my dental clinic in Izmir, in Turkish,
wait until it is ready and send me the preview link.Safety and cost
- Only create_site spends balance. The other five tools only read.
- Use a separate key for assistants. Give it an expiry date and a rate limit in the dashboard, and revoke it any time.
- Assistants cannot delete sites, change settings or touch payments: those routes are not exposed as tools.
- Set idempotency_key on create_site so a retry never charges twice. Failed generations are refunded.
- Editing pages, reference images and ZIP downloads stay in the REST API and the dashboard.
Quickstart
Three calls take you from a brief to a downloadable site. Replace YOUR_API_KEY with a key from the dashboard.
1. Start a generation
POST /sites validates your brief, reserves the generation price from your balance and returns immediately.
curl
curl -X POST https://whitepagekit.com/api/v1/sites \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-attempt-1" \
-d '{"title":"Alder House","lang":"en","sector":"guesthouse","keywords":"quiet stay, harbour","structure":"onepage"}'The response is 202 Accepted with the new site:
202 Accepted
{
"success": true,
"data": {
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"title": "Alder House",
"lang": "en",
"preview_url": null,
"download_url": null
}
}2. Poll the status
Poll GET /sites/{uuid} about every 5–20 seconds until status is done or error, or use a callback URL instead of polling.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. Download the files
A finished site downloads as a ZIP. format is multi or onepage; assets is inline or external.
curl
curl -o site.zip \
-H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000/download?format=multi&assets=inline"The same flow in code
PHP
<?php
$ch = curl_init('https://whitepagekit.com/api/v1/sites');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WPK_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order-1042-attempt-1',
],
CURLOPT_POSTFIELDS => json_encode(['title' => 'Alder House', 'lang' => 'en']),
]);
$site = json_decode(curl_exec($ch), true)['data'];
do {
sleep(5);
$ch = curl_init('https://whitepagekit.com/api/v1/sites/' . $site['uuid']);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('WPK_API_KEY')]]);
$site = json_decode(curl_exec($ch), true)['data'];
} while ($site['status'] === 'pending');Node.js
const headers = {
Authorization: `Bearer ${process.env.WPK_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1042-attempt-1',
};
let { data: site } = await (await fetch('https://whitepagekit.com/api/v1/sites', {
method: 'POST', headers,
body: JSON.stringify({ title: 'Alder House', lang: 'en' }),
})).json();
while (site.status === 'pending') {
await new Promise((r) => setTimeout(r, 5000));
({ data: site } = await (await fetch(`https://whitepagekit.com/api/v1/sites/${site.uuid}`, { headers })).json());
}Python
import os, time, requests
headers = {"Authorization": f"Bearer {os.environ['WPK_API_KEY']}",
"Idempotency-Key": "order-1042-attempt-1"}
site = requests.post("https://whitepagekit.com/api/v1/sites", headers=headers,
json={"title": "Alder House", "lang": "en"}).json()["data"]
while site["status"] == "pending":
time.sleep(5)
site = requests.get(f"https://whitepagekit.com/api/v1/sites/{site['uuid']}", headers=headers).json()["data"]Authentication
Send an API key with every request except the OpenAPI document. Keep keys on your server; never put them in browser code or URLs.
- Header: Authorization: Bearer YOUR_API_KEY, or X-API-Key: YOUR_API_KEY.
- Create, revoke and rate-limit keys in the dashboard. Keys can have an expiry date and an IP allow-list.
- You only see your own sites. A site owned by another account returns 404 not_found.
- Add ?lang=xx or Accept-Language to localize error messages.
Idempotency
Send Idempotency-Key (8–80 characters: letters, digits, _ and -) on POST /sites. Repeating the same key returns the original site and never charges twice, so retries after a timeout are safe. Use a new key to retry a failed generation.
Webhooks (callbacks)
Pass callback_url to POST /sites (or set an account webhook) and receive one JSON POST when the job finishes (site.completed) or fails (site.failed).
POST callback_url
{
"event": "site.completed",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"status": "done",
"site_title": "Alder House",
"lang": "en",
"domain": null,
"created_at": "2026-01-15T09:30:00+00:00",
"preview_url": "https://whitepagekit.com/preview?uuid=550e8400-…"
}When the account has a webhook secret, every request carries X-Webhook-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body. Verify it before parsing the JSON, using a constant-time comparison:
PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}Node.js
import crypto from 'node:crypto';
const expected = 'sha256=' + crypto
.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const received = req.get('x-webhook-signature') ?? '';
const ok = received.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));Each callback is attempted once with a 10-second timeout and is not retried. Treat it as a notification and reconcile with GET /sites/{uuid}. Handle repeats idempotently by uuid and event. Private-network targets are rejected.
Errors
Every response uses an envelope. Errors carry a stable code, a localized message and, for validation errors, the failing field.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | Error codes |
|---|---|
| 400 | validation_error, invalid_json, invalid_webhook_url |
| 401 | missing_api_key |
| 402 | insufficient_balance |
| 403 | api_disabled, invalid_api_key, forbidden |
| 404 | not_found, route_not_found |
| 405 | method_not_allowed |
| 409 | site_not_ready, conflict, edits_reset_required |
| 413 | payload_too_large |
| 415 | unsupported_media_type |
| 429 | rate_limited |
| 500 | internal_error, export_failed |
| 502 | generation_failed |
Limits
| Limit | Value |
|---|---|
| Requests per key | 60 per minute by default (configurable per key, 0 = unlimited). Repeated invalid keys from one IP get 429 with Retry-After. |
| Request body | 2 MB; POST /sites with reference images up to 162 MB; editor saves up to 4 MB. |
| Reference images | Up to 12 PNG, JPEG or WEBP images (base64 or data URL), at most 10 MB each. |
| Editor page content | HTML up to 500,000 characters, CSS up to 100,000. Scripts and event handlers are removed. |
| Site images | PNG, JPEG, WEBP or GIF, 5 MB each, up to 200 per site. |
| Site title | Site title 1–200 characters. |
Editor API
Everything the dashboard editor does is available for your finished sites: page content, page and section plan, style, title/theme/layout/structure, tracking and images. Page edits replace the page; DELETE restores the generated page.
curl
# Load, change and save a page
curl -H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"
curl -X PATCH https://whitepagekit.com/api/v1/sites/UUID/editor \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"page":"index","html":"<main>…</main>","css":""}'
# Restore the generated page
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"Editing needs a completed site (409 site_not_ready otherwise). Changing theme, layout or structure over edited pages returns 409 edits_reset_required unless reset_edits is true. Editing is free.
Endpoint reference
Generated from the OpenAPI document, so it always matches the live API. Paths are relative to the base URL.
Account
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
Catalog
-
GET
/languagesList enabled supported languages
-
GET
/themesList site themes
-
GET
/layoutsList enabled layouts
Sites
-
GET
/sitesList the authenticated account's sites
-
POST
/sitesStart site generation
-
GET
/sites/{uuid}Get site status and refresh generation state
-
DELETE
/sites/{uuid}Delete a terminal site and its generated data — Pending, queued and running generation jobs cannot be deleted. Wait for done or error; active deletion returns 409 conflict without refunding or removing the job.
-
GET
/sites/{uuid}/downloadDownload a completed site archive
AI and automation
-
GET
/ai-toolsFunction-calling tool schemas — The same six tools the MCP endpoint offers, as JSON schemas for your own tool loop. format is openai (Responses API), openai-chat (Chat Completions), anthropic or mcp. Public; no response envelope.
-
GET
/docs.mdDocumentation as Markdown — The developer guide, endpoint reference and AI integration guide as one Markdown file, written for language models and quick copy-paste. Public.
-
POST
/mcpModel Context Protocol endpoint — MCP over Streamable HTTP (JSON-RPC 2.0, one JSON reply per POST). Methods: initialize, ping, tools/list, tools/call. Tools: get_account, list_languages, list_themes, create_site (paid), get_site, list_sites. Authenticate with the same API key; point an MCP client at this URL.
Editor
-
GET
/sites/{uuid}/editorLoad a page for editing — Editor access for the site owner's API key; mirrors the dashboard editor. Only completed sites (409 site_not_ready otherwise).
-
PATCH
/sites/{uuid}/editorSave a page's edited content — Replaces the page content and CSS. html must be non-empty (use DELETE to restore the generated page); scripts, event handlers and javascript: URLs are removed, HTML is limited to 500000 and CSS to 100000 characters, request body to 4 MB. Returns the saved page as GET does.
-
DELETE
/sites/{uuid}/editorRestore a page's generated content — Discards the page's saved edits. Returns the regenerated page.
-
GET
/sites/{uuid}/editor/canvasGet editing canvas data — Stylesheet, Tailwind theme, body class, direction, section blocks, icons and sample copy an external visual editor needs to render the page like the dashboard editor.
-
GET
/sites/{uuid}/pagesGet the page and section plan — Returns structure, pages with their sections and edited flag, one-page sections and the sections available to add. Same payload as the dashboard.
-
POST
/sites/{uuid}/pagesSave the page and section plan — Body: pages (list of {slug, title, nav, sections}; the first page is index) and, for onepage sites, onepage_sections. Sections of pages with saved edits are locked in the dashboard; edited pages that are removed lose their edits. At most 12 pages.
-
GET
/sites/{uuid}/styleGet style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.
-
POST
/sites/{uuid}/styleSave or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.
-
GET
/sites/{uuid}/designGet site title, theme and layout — Returns site_title, title_suggestions, theme_variant, theme_mode, layout, structure and whether the site has saved edits.
-
POST
/sites/{uuid}/designChange site title, theme, mode, layout or structure — theme_variant, theme_mode, layout and structure are required; site_title (1-200 characters), apply_blueprint and reset_edits are optional. Changing theme, layout or structure while pages have saved edits returns 409 edits_reset_required unless reset_edits is true; renaming alone keeps edits.
-
GET
/sites/{uuid}/trackingGet tracking settings
-
POST
/sites/{uuid}/trackingSave tracking settings — Body: tracking {ga4_measurement_id, google_ads_id, google_ads_conversion_label, meta_pixel_id, privacy_policy_url, terms_url}. Applied to exports; an empty object removes all tracking.
-
GET
/sites/{uuid}/mediaList uploaded site images
-
POST
/sites/{uuid}/mediaUpload or delete site images — multipart/form-data with one or more files in files[] (PNG, JPEG, WEBP or GIF, 5 MB each, at most 200 images per site), or JSON {"action": "delete", "name": <name>}. Returns the updated list for uploads. 409 conflict when the per-site image limit is reached.
External payments (administrator keys only)
-
GET
/payment-sitesList external payment sites owned by the admin API account — Admin role required; payment.manage permission alone is insufficient. Webhook secrets are never returned.
-
POST
/payment-sitesRegister an external payment site (admin only)
-
PATCH
/payment-sites/{id}Update an owned external payment site (admin only)
-
DELETE
/payment-sites/{id}Delete an owned external payment site (admin only) — Deletion is allowed only when the site has no orders. Sites with orders must be disabled instead.
-
GET
/paymentsList external orders owned by the admin API account
-
POST
/paymentsCreate external checkout or automatic subscription (admin only) — Server-to-server only. Separate from wallet top-ups: no White Page Kit balance, bonus or referral credit. Repeated idempotency key returns the original order; a different payload or reused external order ID conflicts. Provider uncertainty never starts a second checkout automatically.
-
GET
/payments/{uuid}Read owned external payment status (admin only)
-
POST
/payments/{uuid}/cancelCancel an owned subscription or locally close a pending one-time order (admin only) — Subscriptions stop future renewals. Pending one-time cancellation is a local close, not a refund; an already-open provider checkout may still accept payment. A late authenticated real payment remains recorded and notified. No payment is marked paid by a browser return.
-
POST
/payments/{uuid}/approveApprove funds received for an owned pending or locally cancelled bank transfer (admin only) — Manual confirmation of funds received, including a transfer arriving after local cancellation; never approves a Dodo or Enigmoss order and never credits White Page Kit balance.
Descriptions come from the OpenAPI document and are in English. Request and response schemas are in the schema file.
Ready-made integrations
The integration kit is a small PHP application with a generator form, status polling, signed-callback guidance and a full visual editor that talks to this API through a server-side proxy. Create an account to get a key, then see pricing for what each generation costs.