Documentazione API
Crea siti whitepage, segui i loro progressi e scarica i file dal tuo codice, da uno strumento no-code o semplicemente chiedendo a un assistente AI. Ogni richiesta è JSON via HTTPS.
Come funziona
Tre passaggi, qualunque sia il metodo di connessione:
- Crea una chiave API Accedi, apri le chiavi API nel pannello di controllo e crea una chiave. Funziona come una password per il tuo account, quindi mantienila privata.
- Richiedi un sito Invia un titolo e una lingua, e se vuoi anche l'argomento, il pubblico e le parole chiave. Il prezzo di generazione sarà detratto dal tuo saldo e il sito inizierà a essere costruito.
- Raccogli il tuo sito Di solito è pronto in pochi minuti. Controlla lo stato, oppure lascia che chiamiamo il tuo URL quando termina, quindi visualizza l'anteprima, modifica e scarica i file.
Scegli come connetterti
- Uso un assistente AI Claude, ChatGPT, Cursor e altri possono creare e monitorare siti per te.
- Scrivo codice Tre chiamate REST, con esempi in curl, PHP, Node.js e Python.
- Uso uno strumento no-code Qualsiasi cosa che può inviare una richiesta HTTP, come Zapier, Make o n8n, può eseguire le stesse tre chiamate.
Strumenti no-code: qualsiasi cosa che può inviare una richiesta HTTP (Zapier, Make, n8n, uno script di foglio di calcolo) può eseguire le stesse chiamate. POST /sites avvia un sito; GET /sites/{uuid} su timer, o un callback_url, ti dice quando è finito. Metti la chiave API nell'intestazione Authorization.
Termini chiave
- Sito
- Un sito web generato con tutte le sue pagine. È identificato da un uuid.
- Stato
- in sospeso mentre costruisce, completato quando è pronto, errore se è fallito. Un sito fallito viene rimborsato automaticamente.
- Chiave API
- Una stringa segreta che dimostra che una richiesta proviene dal tuo account. Crea e revoca chiavi nella dashboard.
- Saldo
- Denaro prepagato nel tuo account. Creare un sito riserva da esso il prezzo di generazione.
- Callback
- Un URL tuo che chiamiamo una volta quando un sito finisce, così non devi continuare a controllare.
- Chiave di idempotenza
- Un'etichetta che assegni a una richiesta in modo che inviarla due volte non crei mai, o addebiti, due siti.
Usalo con assistenti AI
Collega un assistente AI e semplicemente chiedi: "Crea un sito per la mia clinica dentistica, in turco." L'assistente chiama la stessa API sotto il tuo account. Rimani in controllo: creare un sito costa equilibrio, e buoni assistenti ti chiedono prima di farlo.
Cose che puoi dire
- Quanto saldo ho e quanto costa un sito?
- Quali kit di design sono adatti per una panetteria?
- Create un sito one-page per Alder House, un tranquillo bed and breakfast sul porto, in inglese.
- Il mio sito è pronto? Inviami il link di anteprima.
Collegati tramite MCP (Claude, Cursor e altri)
MCP è lo standard aperto che gli assistenti usano per chiamare strumenti esterni. Punta il tuo assistente all'URL MCP e fornisci la tua chiave API come 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 grezzo
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 raggiunge i server remoti tramite il ponte mcp-remote, che richiede Node.js.
ChatGPT (GPT personalizzato)
- In ChatGPT crea un GPT, apri Configura e scegli Crea nuova azione.
- Scegli Importa da URL e incolla https://whitepagekit.com/api/v1/openapi.json?profile=assistant. Questo schema semplificato contiene solo i sei strumenti per assistenti.
- Sotto Autenticazione scegli Chiave API, imposta Tipo di autenticazione su Bearer e incolla la tua chiave API.
- ChatGPT ti chiede di confermare le richieste che modificano qualcosa, così mantieni il controllo su tutto ciò che costa saldo.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantOpenAI API (strumento MCP)
L’API Risposte può usare l’URL MCP come strumento remoto. require_approval tiene un umano nel 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)Il tuo ciclo di strumenti (chiamata di funzione)
Se gestisci tu stesso il ciclo modello, recupera schemi di strumenti già pronti ed esegui ogni chiamata strumento verso il relativo endpoint REST. Formati: openai (API Risposte), openai-chat, anthropic e mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcpI sei strumenti
| Strumento | Cosa fa | Chiamata REST | Costo |
|---|---|---|---|
get_account |
Mostra il tuo saldo e quanto costa un sito. | GET /me |
Gratuito |
list_languages |
Elenca le lingue in cui un sito può essere scritto. | GET /languages |
Gratuito |
list_themes |
Cerca i kit di design per argomento o stile. | GET /themes |
Gratuito |
create_site |
Inizia a generare un sito e preleva il costo di generazione dal tuo saldo. | POST /sites |
Usa il saldo |
get_site |
Mostra un sito: progresso, link di anteprima e link per il download. | GET /sites/{uuid} |
Gratuito |
list_sites |
Elenca i tuoi siti, dal più recente al più vecchio. | GET /sites |
Gratuito |
Dai qualsiasi documento all'IA
Questa pagina è anche disponibile in Markdown semplice, ideale per incollare in una chat o passare a un assistente di codifica:
Markdown
https://whitepagekit.com/api/v1/docs.mdUn prompt che puoi incollare
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.Sicurezza e costo
- Solo create_site consuma il saldo. Gli altri cinque strumenti sono solo di lettura.
- Usa una chiave separata per gli assistenti. Imposta una data di scadenza e un limite di velocità nella dashboard, e revocala in qualsiasi momento.
- Gli assistenti non possono eliminare siti, modificare le impostazioni o gestire i pagamenti: queste funzionalità non sono esposte come strumenti.
- Imposta idempotency_key su create_site così un ritentativo non addebiterà due volte. Le generazioni fallite vengono rimborsate.
- La modifica delle pagine, le immagini di riferimento e i download ZIP rimangono nell'API REST e nella dashboard.
Avvio rapido
Tre chiamate ti portano da un brief a un sito scaricabile. Sostituisci YOUR_API_KEY con una chiave dalla dashboard.
1. Avvia una generazione
POST /sites convalida il tuo brief, riserva il prezzo della generazione dal tuo saldo e restituisce immediatamente.
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 risposta è 202 Accepted con il nuovo sito:
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. Interroga lo stato
Interroga GET /sites/{uuid} ogni 5–20 secondi finché lo stato non è done o error, oppure usa un URL di callback invece di interrogare.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. Scarica i file
Un sito finito si scarica come ZIP. Il formato è multi o onepage; le risorse sono inline o esterne.
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"Lo stesso flusso nel codice
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"]Autenticazione
Invia una chiave API con ogni richiesta tranne il documento OpenAPI. Tieni le chiavi sul tuo server; non metterle mai nel codice del browser o negli URL.
- Intestazione: Authorization: Bearer YOUR_API_KEY, oppure X-API-Key: YOUR_API_KEY.
- Crea, revoca e limita la frequenza delle chiavi nella dashboard. Le chiavi possono avere una data di scadenza e una lista di IP consentiti.
- Vedi solo i tuoi siti. Un sito di un altro account restituisce 404 not_found.
- Aggiungi ?lang=xx o Accept-Language per localizzare i messaggi di errore.
Idempotenza
Invia Idempotency-Key (8–80 caratteri: lettere, cifre, _ e -) su POST /sites. Ripetere la stessa chiave restituisce il sito originale e non addebita mai due volte, quindi i ritentativi dopo un timeout sono sicuri. Usa una nuova chiave per ritentare una generazione fallita.
Webhooks (callback)
Passa callback_url a POST /sites (o imposta un webhook per l'account) e ricevi un POST JSON quando il lavoro termina (site.completed) o fallisce (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 l'account ha un webhook secret, ogni richiesta porta X-Webhook-Signature: sha256=<hex>, un HMAC-SHA256 del corpo grezzo. Verificalo prima di analizzare il JSON, usando un confronto a tempo costante:
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));Ogni callback viene tentato una volta con un timeout di 10 secondi e non viene ritentato. Trattalo come una notifica e riconcilialo con GET /sites/{uuid}. Gestisci ripetizioni in modo idempotente per uuid ed evento. Gli obiettivi in rete privata vengono rifiutati.
Errori
Ogni risposta usa una busta. Gli errori riportano un codice stabile, un messaggio localizzato e, per errori di validazione, il campo che ha fallito.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | Codici di errore |
|---|---|
| 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 |
Limiti
| Limite | Valore |
|---|---|
| Richieste per chiave | 60 per minuto di default (configurabile per chiave, 0 = illimitato). Chiavi non valide ripetute da un IP ricevono 429 con Retry-After. |
| Corpo della richiesta | 2 MB; POST /sites con immagini di riferimento fino a 162 MB; salvataggi dell'editor fino a 4 MB. |
| Immagini di riferimento | Fino a 12 immagini PNG, JPEG o WEBP (base64 o data URL), massimo 10 MB ciascuna. |
| Contenuto della pagina dell'editor | HTML fino a 500.000 caratteri, CSS fino a 100.000. Script e gestori di eventi sono rimossi. |
| Immagini del sito | PNG, JPEG, WEBP o GIF, 5 MB ciascuna, fino a 200 per sito. |
| Titolo del sito | Titolo del sito 1–200 caratteri. |
Editor API
Tutto ciò che fa l'editor della dashboard è disponibile per i tuoi siti finiti: contenuto della pagina, piano della pagina e della sezione, stile, titolo/tema/layout/struttura, tracciamento e immagini. Le modifiche alla pagina sostituiscono la pagina; DELETE ripristina la pagina generata.
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 modifica richiede un sito completato (altrimenti 409 site_not_ready). Cambiare tema, layout o struttura su pagine modificate restituisce 409 edits_reset_required a meno che reset_edits non sia true. La modifica è gratuita.
Riferimento endpoint
Generato dal documento OpenAPI, quindi corrisponde sempre all'API live. I percorsi sono relativi all'URL base.
Account
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
Catalogo
-
GET
/languagesList enabled supported languages
-
GET
/themesList site themes
-
GET
/layoutsList enabled layouts
Siti
-
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 e automazione
-
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.
Pagamenti esterni (solo chiavi amministratore)
-
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.
Le descrizioni provengono dal documento OpenAPI e sono in inglese. Gli schemi di richiesta e risposta sono nel file schema.
Integrazioni pronte all'uso
Il kit di integrazione è una piccola applicazione PHP con un modulo generatore, polling dello stato, guida per callback firmati e un editor visivo completo che parla con questa API tramite un proxy server-side. Crea un account per ottenere una chiave, poi consulta i prezzi per sapere i costi di ogni generazione.