Documentación de API
Crea sitios whitepage, sigue su progreso y descarga los archivos desde tu propio código, desde una herramienta sin código o simplemente pidiendo a un asistente de IA. Cada solicitud es JSON sobre HTTPS.
Cómo funciona
Tres pasos, sea como sea que te conectes:
- Crea una clave API Inicia sesión, abre las claves API en el panel y crea una. Funciona como una contraseña para tu cuenta, así que mantenla privada.
- Solicita un sitio Envía un título y un idioma, y si gustas, el tema, la audiencia y las palabras clave. El precio de generación se tomará de tu saldo y el sitio comenzará a construirse.
- Recoge tu sitio Por lo general, está listo en minutos. Revisa su estado, o déjanos llamar a tu URL cuando termine, luego previsualiza, edita y descarga los archivos.
Elige cómo te conectas
- Uso un asistente de IA Claude, ChatGPT, Cursor y otros pueden crear y rastrear sitios para ti.
- Escribo código Tres llamadas REST, con ejemplos en curl, PHP, Node.js y Python.
- Uso una herramienta sin código Cualquier cosa que pueda enviar una solicitud HTTP, como Zapier, Make o n8n, puede ejecutar las mismas tres llamadas.
Herramientas sin código: cualquier cosa que pueda enviar una solicitud HTTP (Zapier, Make, n8n, un script de hoja de cálculo) puede ejecutar las mismas llamadas. POST /sites inicia un sitio; GET /sites/{uuid} en un temporizador, o un callback_url, te dice cuándo está listo. Pon la clave API en el encabezado Authorization.
Términos clave
- Sitio
- Un sitio web generado con todas sus páginas. Se identifica por un uuid.
- Estado
- pendiente mientras se construye, terminado cuando está listo, error si falló. Un sitio fallido se reembolsa automáticamente.
- Clave API
- Una cadena secreta que prueba que una solicitud proviene de tu cuenta. Crea y revoca claves en el panel de control.
- Saldo
- Dinero prepago en tu cuenta. Crear un sitio reserva el precio de generación de él.
- Llamada de retorno
- Una URL tuya que llamamos una vez cuando un sitio termina, así no tienes que estar revisando.
- Clave de idempotencia
- Una etiqueta que adjuntas a una solicitud para que enviarla dos veces nunca cree o cobre por dos sitios.
Úsalo con asistentes de IA
Conecta un asistente de IA y simplemente pide: "Haz un sitio para mi clínica dental, en turco." El asistente llama a la misma API bajo tu cuenta. Tú mantienes el control: crear un sitio cuesta saldo, y los buenos asistentes te preguntan antes de hacerlo.
Cosas que puedes decir
- ¿Cuánto saldo tengo y cuánto cuesta un sitio?
- ¿Qué kits de diseño son adecuados para una panadería?
- Crea un sitio de una página para Alder House, una casa de huéspedes tranquila en el puerto, en inglés.
- ¿Está listo mi sitio? Envíame el enlace de vista previa.
Conectar a través de MCP (Claude, Cursor y más)
MCP es el estándar abierto que los asistentes usan para llamar a herramientas externas. Dirige tu asistente a la URL de MCP y proporciona tu clave API como token Bearer.
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" }
}
}
}JSON-RPC puro
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 accede a servidores remotos a través del puente mcp-remote, que necesita Node.js.
ChatGPT (GPT personalizado)
- En ChatGPT crea un GPT, abre Configurar y elige Crear nueva acción.
- Elige Importar desde URL y pega https://whitepagekit.com/api/v1/openapi.json?profile=assistant. Este esquema recortado contiene solo las seis herramientas del asistente.
- En Autenticación elige Clave API, establece Tipo de Autenticación en Bearer y pega tu clave API.
- ChatGPT te pide que confirmes las solicitudes que cambian algo, para que mantengas el control de todo lo que cuesta saldo.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantAPI de OpenAI (herramienta MCP)
La API de Respuestas puede usar la URL MCP como herramienta remota. require_approval mantiene a un humano en el proceso.
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)Tu propio ciclo de herramientas (llamado de funciones)
Si ejecutas el ciclo del modelo tú mismo, descarga esquemas de herramientas listas y ejecuta cada llamada a herramienta contra el endpoint REST correspondiente. Formatos: openai (API de Respuestas), openai-chat, anthropic y mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcpLas seis herramientas
| Herramienta | Lo que hace | Llamada REST | Costo |
|---|---|---|---|
get_account |
Muestra tu saldo y cuánto cuesta un sitio. | GET /me |
Gratis |
list_languages |
Lista los idiomas en los que se puede escribir un sitio. | GET /languages |
Gratis |
list_themes |
Busca los kits de diseño por tema o estilo. | GET /themes |
Gratis |
create_site |
Comienza a generar un sitio y toma el precio de generación de tu saldo. | POST /sites |
Usa saldo |
get_site |
Muestra un sitio: progreso, enlace de vista previa y enlace de descarga. | GET /sites/{uuid} |
Gratis |
list_sites |
Lista tus sitios, los más nuevos primero. | GET /sites |
Gratis |
Da estos documentos a cualquier IA
Esta página también está disponible como Markdown simple, ideal para pegar en un chat o pasar a un asistente de codificación:
Markdown
https://whitepagekit.com/api/v1/docs.mdUn prompt que puedes pegar
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.Seguridad y costo
- Solo create_site consume saldo. Las otras cinco herramientas solo leen.
- Usa una clave separada para asistentes. Ponle una fecha de expiración y un límite de tasa en el panel, y revócala cuando quieras.
- Los asistentes no pueden eliminar sitios, cambiar configuraciones ni tocar pagos: esas rutas no están expuestas como herramientas.
- Establece idempotency_key en create_site para que un reintento nunca cobre dos veces. Las generaciones fallidas se reembolsan.
- La edición de páginas, imágenes de referencia y descargas ZIP permanecen en la API REST y el panel de control.
Inicio rápido
Tres llamadas te llevan de un resumen a un sitio descargable. Reemplaza YOUR_API_KEY con una clave del panel de control.
1. Iniciar una generación
POST /sites valida tu resumen, reserva el precio de generación de tu saldo y responde inmediatamente.
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"}'La respuesta es 202 Accepted con el nuevo sitio:
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. Consulta el estado
Consulta GET /sites/{uuid} cada 5–20 segundos hasta que el estado sea done o error, o usa una URL de callback en lugar de hacer polling.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. Descarga los archivos
Un sitio terminado se descarga como un archivo ZIP. El formato puede ser multi o onepage; los recursos pueden estar inline o externos.
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"El mismo flujo en código
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"]Autenticación
Envía una clave API con cada solicitud excepto con el documento OpenAPI. Mantén las claves en tu servidor; nunca las pongas en código del navegador o URLs.
- Cabecera: Authorization: Bearer YOUR_API_KEY, o X-API-Key: YOUR_API_KEY.
- Crea, revoca y limita la tasa de claves en el panel de control. Las claves pueden tener una fecha de expiración y una lista blanca de IPs.
- Solo ves tus propios sitios. Un sitio propiedad de otra cuenta devuelve 404 not_found.
- Agrega ?lang=xx o Accept-Language para localizar los mensajes de error.
Idempotencia
Envía Idempotency-Key (8–80 caracteres: letras, dígitos, _ y -) en POST /sites. Repetir la misma clave devuelve el sitio original y nunca cobra dos veces, por lo que los reintentos tras un timeout son seguros. Usa una clave nueva para reintentar una generación fallida.
Webhooks (callbacks)
Pasa callback_url a POST /sites (o configura un webhook de cuenta) y recibe un POST JSON cuando el trabajo termina (site.completed) o falla (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-…"
}Cuando la cuenta tiene un secreto webhook, cada solicitud lleva X-Webhook-Signature: sha256=<hex>, un HMAC-SHA256 del cuerpo sin procesar. Verifícalo antes de analizar el JSON, usando una comparación en tiempo constante:
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));Cada callback se intenta una vez con un tiempo límite de 10 segundos y no se reintenta. Trátalo como una notificación y concílialo con GET /sites/{uuid}. Maneja repeticiones idempotentemente por uuid y evento. Se rechazan los destinos de red privada.
Errores
Cada respuesta usa un sobre. Los errores llevan un código estable, un mensaje localizado y, para errores de validación, el campo que falla.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | Códigos de error |
|---|---|
| 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 |
Límites
| Límite | Valor |
|---|---|
| Solicitudes por clave | 60 por minuto por defecto (configurable por clave, 0 = ilimitado). Claves inválidas repetidas desde una IP reciben 429 con Retry-After. |
| Cuerpo de la solicitud | 2 MB; POST /sites con imágenes de referencia hasta 162 MB; el editor guarda hasta 4 MB. |
| Imágenes de referencia | Hasta 12 imágenes PNG, JPEG o WEBP (base64 o URL de datos), máximo 10 MB cada una. |
| Contenido de la página del editor | HTML hasta 500,000 caracteres, CSS hasta 100,000. Se eliminan scripts y manejadores de eventos. |
| Imágenes del sitio | PNG, JPEG, WEBP o GIF, 5 MB cada una, hasta 200 por sitio. |
| Título del sitio | Título del sitio 1–200 caracteres. |
Editor API
Todo lo que hace el editor del panel está disponible para tus sitios terminados: contenido de la página, plan de página y sección, estilo, título/tema/diseño/estructura, seguimiento e imágenes. Las ediciones en la página reemplazan la página; DELETE restaura la página generada.
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"La edición requiere un sitio completado (409 site_not_ready en caso contrario). Cambiar el tema, diseño o estructura sobre páginas editadas devuelve 409 edits_reset_required a menos que reset_edits sea true. Editar es gratis.
Referencia del endpoint
Generado a partir del documento OpenAPI, por lo que siempre coincide con la API en vivo. Las rutas son relativas a la URL base.
Cuenta
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
Catálogo
-
GET
/languagesList enabled supported languages
-
GET
/themesList site themes
-
GET
/layoutsList enabled layouts
Sitios
-
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
IA y automatización
-
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.
Pagos externos (solo claves de administrador)
-
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.
Las descripciones provienen del documento OpenAPI y están en inglés. Los esquemas de solicitud y respuesta están en el archivo de esquema.
Integraciones prefabricadas
El kit de integración es una pequeña aplicación PHP con un formulario generador, sondeo de estado, orientación sobre callbacks firmados y un editor visual completo que se comunica con esta API a través de un proxy del lado del servidor. Crea una cuenta para obtener una clave, luego consulta los precios por cada generación.