Documentação da API
Crie sites whitepage, acompanhe seu progresso e baixe os arquivos a partir do seu próprio código, de uma ferramenta no-code ou simplesmente pedindo a um assistente de IA. Toda requisição é JSON via HTTPS.
Como funciona
Três passos, independentemente de como você se conecte:
- Crie uma chave API Entre, abra as chaves API no painel e crie uma chave. Ela funciona como uma senha para sua conta, portanto mantenha-a em sigilo.
- Peça um site Envie um título e um idioma, e se desejar, o tópico, o público e as palavras-chave. O preço da geração será deduzido do seu saldo e o site começará a ser construído.
- Colete seu site Normalmente fica pronto em alguns minutos. Verifique seu status ou permita que chamemos sua URL quando terminar, então visualize, edite e baixe os arquivos.
Escolha como você se conecta
- Eu uso um assistente de IA Claude, ChatGPT, Cursor e outros podem criar e rastrear sites para você.
- Eu escrevo código Três chamadas REST, com exemplos em curl, PHP, Node.js e Python.
- Eu uso uma ferramenta no-code Qualquer coisa que possa enviar uma requisição HTTP, como Zapier, Make ou n8n, pode executar as mesmas três chamadas.
Ferramentas no-code: qualquer coisa que possa enviar uma requisição HTTP (Zapier, Make, n8n, um script de planilha) pode executar as mesmas chamadas. POST /sites inicia um site; GET /sites/{uuid}, em um temporizador ou um callback_url, informa quando está concluído. Coloque a chave da API no cabeçalho Authorization.
Termos-chave
- Site
- Um site gerado com todas as suas páginas. É identificado por um uuid.
- Estado
- pendente enquanto está sendo construído, concluído quando está pronto, erro se falhou. Um site com falha é reembolsado automaticamente.
- Chave da API
- Uma string secreta que prova que uma requisição vem da sua conta. Crie e revogue chaves no painel de controle.
- Saldo
- Dinheiro pré-pago em sua conta. Criar um site reserva o preço da geração a partir dele.
- Callback
- Uma URL sua que chamamos uma vez quando um site termina, para que você não precise ficar verificando.
- Chave de idempotência
- Um rótulo que você anexa a uma requisição para que enviá-la duas vezes nunca crie, ou cobre por, dois sites.
Use com assistentes de IA
Conecte um assistente de IA e simplesmente pergunte: "Faça um site para minha clínica odontológica, em turco." O assistente chama a mesma API na sua conta. Você mantém o controle: criar um site custa saldo, e bons assistentes perguntam antes de fazer isso.
Coisas que você pode dizer
- Quanto saldo eu tenho e quanto custa um site?
- Quais kits de design são adequados para uma padaria?
- Create a one-page site for Alder House, a quiet harbour guesthouse, in English.
- Meu site está pronto? Envie-me o link de visualização.
Conectar via MCP (Claude, Cursor e mais)
MCP é o padrão aberto que os assistentes usam para chamar ferramentas externas. Aponte seu assistente para o URL do MCP e forneça sua chave 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 bruto
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 alcança servidores remotos através da ponte mcp-remote, que precisa do Node.js.
ChatGPT (GPT personalizado)
- No ChatGPT crie um GPT, abra Configurar e escolha Criar nova ação.
- Escolha Importar de URL e cole https://whitepagekit.com/api/v1/openapi.json?profile=assistant. Este esquema reduzido contém apenas as seis ferramentas do assistente.
- Em Autenticação escolha Chave API, defina o Tipo de Autenticação para Bearer e cole sua chave API.
- O ChatGPT pede que você confirme solicitações que alteram algo, para que você mantenha o controle sobre qualquer coisa que custe saldo.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantAPI OpenAI (ferramenta MCP)
A API de Respostas pode usar o URL do MCP como uma ferramenta remota. require_approval mantém um humano no processo.
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)Seu próprio loop de ferramenta (chamada de função)
Se você mesmo executar o loop do modelo, obtenha esquemas de ferramentas prontos e execute cada chamada de ferramenta no endpoint REST correspondente. Formatos: openai (API de Respostas), openai-chat, anthropic e mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcpAs seis ferramentas
| Ferramenta | O que faz | Chamada REST | Custo |
|---|---|---|---|
get_account |
Mostra seu saldo e quanto custa um site. | GET /me |
Grátis |
list_languages |
Lista os idiomas nos quais um site pode ser escrito. | GET /languages |
Grátis |
list_themes |
Pesquisa os kits de design por tópico ou estilo. | GET /themes |
Grátis |
create_site |
Inicia a geração de um site e desconta o preço da geração do seu saldo. | POST /sites |
Usa saldo |
get_site |
Mostra um site: progresso, link de pré-visualização e link de download. | GET /sites/{uuid} |
Grátis |
list_sites |
Lista seus sites, do mais novo para o mais antigo. | GET /sites |
Grátis |
Dê qualquer documentação para a IA
Esta página também está disponível em Markdown simples, ideal para colar em um chat ou entregar a um assistente de codificação:
Markdown
https://whitepagekit.com/api/v1/docs.mdUm prompt que você pode colar
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.Segurança e custo
- Apenas create_site consome saldo. As outras cinco ferramentas apenas leem.
- Use uma chave separada para assistentes. Defina uma data de expiração e um limite de taxa no painel, e revogue-a a qualquer momento.
- Assistentes não podem deletar sites, alterar configurações ou mexer em pagamentos: essas rotas não são expostas como ferramentas.
- Defina idempotency_key em create_site para que uma nova tentativa nunca cobre duas vezes. Gerações falhadas são reembolsadas.
- Edição de páginas, imagens de referência e downloads ZIP permanecem na API REST e no painel.
Início rápido
Três chamadas levam você de um briefing a um site para download. Substitua YOUR_API_KEY por uma chave do painel.
1. Iniciar uma geração
POST /sites valida seu briefing, reserva o preço da geração do seu saldo e retorna imediatamente.
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"}'A resposta é 202 Accepted com o novo 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. Consultar o status
Consulte GET /sites/{uuid} a cada 5–20 segundos até o status ser feito ou erro, ou use uma URL de callback em vez da consulta.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. Baixar os arquivos
Um site finalizado é baixado como um ZIP. O formato é multi ou onepage; os assets são inline ou 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"O mesmo fluxo em 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"]Autenticação
Envie uma chave API com cada requisição, exceto o documento OpenAPI. Mantenha as chaves no seu servidor; nunca as coloque no código do navegador ou URLs.
- Cabeçalho: Authorization: Bearer YOUR_API_KEY, ou X-API-Key: YOUR_API_KEY.
- Crie, revogue e limite a taxa de chaves no painel. As chaves podem ter data de expiração e uma lista de IPs permitidos.
- Você vê apenas seus próprios sites. Um site pertencente a outra conta retorna 404 not_found.
- Adicione ?lang=xx ou Accept-Language para localizar mensagens de erro.
Idempotência
Envie Idempotency-Key (8–80 caracteres: letras, dígitos, _ e -) no POST /sites. Repetir a mesma chave retorna o site original e nunca cobra duas vezes, então reenvios após um timeout são seguros. Use uma chave nova para tentar gerar novamente um pedido que falhou.
Webhooks (callbacks)
Passe callback_url para POST /sites (ou configure um webhook de conta) e receba um POST JSON quando o trabalho terminar (site.completed) ou falhar (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-…"
}Quando a conta tem um segredo de webhook, cada solicitação carrega X-Webhook-Signature: sha256=<hex>, um HMAC-SHA256 do corpo bruto. Verifique-o antes de analisar o JSON, usando uma comparação em tempo 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 é tentado uma vez com um tempo limite de 10 segundos e não é refeito. Trate-o como uma notificação e faça a conciliação com GET /sites/{uuid}. Trate repetições de forma idempotente por uuid e evento. Destinos de rede privada são rejeitados.
Erros
Cada resposta usa um envelope. Erros carregam um código estável, uma mensagem localizada e, para erros de validação, o campo que falhou.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | Códigos de erro |
|---|---|
| 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 |
Limites
| Limite | Valor |
|---|---|
| Requisições por chave | 60 por minuto por padrão (configurável por chave, 0 = ilimitado). Chaves inválidas repetidas de um IP recebem 429 com Retry-After. |
| Corpo da requisição | 2 MB; POST /sites com imagens de referência até 162 MB; editor salva até 4 MB. |
| Imagens de referência | Até 12 imagens PNG, JPEG ou WEBP (base64 ou URL de dados), no máximo 10 MB cada. |
| Conteúdo da página do editor | HTML até 500.000 caracteres, CSS até 100.000. Scripts e manipuladores de eventos são removidos. |
| Imagens do site | PNG, JPEG, WEBP ou GIF, 5 MB cada, até 200 por site. |
| Título do site | Título do site 1–200 caracteres. |
Editor API
Tudo o que o editor do painel faz está disponível para seus sites finalizados: conteúdo da página, plano de página e seção, estilo, título/tema/layout/estrutura, rastreamento e imagens. As edições da página substituem a página; DELETE restaura a página gerada.
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"Editar requer um site concluído (409 site_not_ready caso contrário). Alterar tema, layout ou estrutura sobre páginas editadas retorna 409 edits_reset_required a menos que reset_edits seja true. Editar é gratuito.
Referência do endpoint
Gerado a partir do documento OpenAPI, para que sempre corresponda à API ao vivo. Os caminhos são relativos à URL base.
Conta
-
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
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
IA e automação
-
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.
Pagamentos externos (apenas chaves 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.
As descrições vêm do documento OpenAPI e estão em inglês. Esquemas de requisição e resposta estão no arquivo de esquema.
Integrações prontas
O kit de integração é uma pequena aplicação PHP com um formulário gerador, sondagem de status, orientação para callbacks assinados e um editor visual completo que se comunica com esta API através de um proxy no servidor. Crie uma conta para obter uma chave e veja os preços para o custo de cada geração.