Documentation de l'API
Créez des sites whitepage, suivez leur progression et téléchargez les fichiers depuis votre propre code, un outil no-code ou simplement en demandant à un assistant IA. Chaque requête est en JSON via HTTPS.
Comment ça marche
Trois étapes, quelle que soit votre méthode de connexion :
- Créez une clé API Connectez-vous, ouvrez les clés API dans le tableau de bord et créez une clé. Elle fonctionne comme un mot de passe pour votre compte, gardez-la privée.
- Demandez un site Envoyez un titre et une langue, ainsi que le sujet, le public et les mots-clés si vous le souhaitez. Le prix de génération est déduit de votre solde et le site commence à se construire.
- Récupérez votre site Il est généralement prêt en quelques minutes. Vérifiez son statut, ou laissez-nous appeler votre URL à la fin, puis prévisualisez, modifiez et téléchargez les fichiers.
Choisissez votre mode de connexion
- J'utilise un assistant IA Claude, ChatGPT, Cursor et d'autres peuvent créer et suivre des sites pour vous.
- J'écris du code Trois appels REST, avec des exemples en curl, PHP, Node.js et Python.
- J'utilise un outil sans code Tout ce qui peut envoyer une requête HTTP, comme Zapier, Make ou n8n, peut exécuter les mêmes trois appels.
Outils sans code : tout ce qui peut envoyer une requête HTTP (Zapier, Make, n8n, un script de feuille de calcul) peut exécuter les mêmes appels. POST /sites démarre un site ; GET /sites/{uuid} sur un minuteur, ou une callback_url, vous indique quand il est terminé. Mettez la clé API dans l'en-tête Authorization.
Termes clés
- Site
- Un site web généré avec toutes ses pages. Il est identifié par un uuid.
- Statut
- en attente pendant sa création, terminé lorsqu'il est prêt, erreur s'il a échoué. Un site défaillant est automatiquement remboursé.
- Clé API
- Une chaîne secrète qui prouve qu'une requête provient de votre compte. Créez et révoquez des clés dans le tableau de bord.
- Solde
- Argent prépayé sur votre compte. Créer un site réserve le prix de génération de celui-ci.
- Rappel (Callback)
- Une URL de votre part que nous appelons une fois qu'un site est terminé, ainsi vous n'avez pas à vérifier continuellement.
- Clé d'idempotence
- Une étiquette que vous attachez à une requête pour que l'envoi en double ne crée pas, ni ne facture, deux sites.
Utilisez-le avec des assistants d'IA
Connectez un assistant d'IA et demandez simplement : « Crée un site pour ma clinique dentaire, en turc. » L'assistant appelle la même API sous votre compte. Vous restez maître : créer un site coûte du solde, et les bons assistants vous demandent avant de le faire.
Choses que vous pouvez dire
- Combien de solde ai-je, et combien coûte un site ?
- Quels kits de design conviennent à une boulangerie ?
- Create a one-page site for Alder House, a quiet harbour guesthouse, in English.
- Mon site est-il prêt ? Envoyez-moi le lien d'aperçu.
Connecter via MCP (Claude, Cursor et plus)
MCP est la norme ouverte utilisée par les assistants pour appeler des outils externes. Pointez votre assistant vers l'URL MCP et donnez-lui votre clé API en tant que jeton 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 brut
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 accède aux serveurs distants via le pont mcp-remote, qui nécessite Node.js.
ChatGPT (GPT personnalisé)
- Dans ChatGPT, créez un GPT, ouvrez Configurer et choisissez Créer une nouvelle action.
- Choisissez Importer depuis URL et collez https://whitepagekit.com/api/v1/openapi.json?profile=assistant. Ce schéma allégé contient uniquement les six outils d'assistant.
- Sous Authentification, choisissez Clé API, réglez le Type d'authentification sur Bearer et collez votre clé API.
- ChatGPT vous demande de confirmer les requêtes qui modifient quelque chose, vous gardez ainsi le contrôle sur tout ce qui coûte du solde.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantAPI OpenAI (outil MCP)
L'API Responses peut utiliser l'URL MCP comme outil distant. require_approval maintient un contrôle humain.
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)Votre propre boucle d'outil (appel de fonction)
Si vous exécutez vous-même la boucle du modèle, récupérez des schémas d'outils prêts à l'emploi et exécutez chaque appel d'outil via le point de terminaison REST correspondant. Formats : openai (API Responses), openai-chat, anthropic et mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcpLes six outils
| Outil | Ce que ça fait | Appel REST | Coût |
|---|---|---|---|
get_account |
Affiche votre solde et le coût d'un site. | GET /me |
Gratuit |
list_languages |
Liste les langues dans lesquelles un site peut être écrit. | GET /languages |
Gratuit |
list_themes |
Recherche les kits de design par sujet ou style. | GET /themes |
Gratuit |
create_site |
Commence à générer un site et prélève le prix de génération de votre solde. | POST /sites |
Utilise le solde |
get_site |
Affiche un site : progression, lien d'aperçu et lien de téléchargement. | GET /sites/{uuid} |
Gratuit |
list_sites |
Liste vos sites, du plus récent au plus ancien. | GET /sites |
Gratuit |
Donnez à n'importe quelle IA ces documents
Cette page est également disponible en Markdown simple, idéal pour coller dans un chat ou la donner à un assistant de codage :
Markdown
https://whitepagekit.com/api/v1/docs.mdUn prompt que vous pouvez coller
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.Sécurité et coût
- Seul create_site dépense du solde. Les cinq autres outils ne font que lire.
- Utilisez une clé distincte pour les assistants. Donnez-lui une date d'expiration et une limite de taux dans le tableau de bord, et révoquez-la à tout moment.
- Les assistants ne peuvent pas supprimer de sites, modifier les paramètres ou toucher aux paiements : ces routes ne sont pas exposées comme outils.
- Définissez idempotency_key sur create_site pour qu'une nouvelle tentative ne soit jamais facturée deux fois. Les générations échouées sont remboursées.
- L'édition des pages, les images de référence et les téléchargements ZIP restent dans l'API REST et le tableau de bord.
Démarrage rapide
Trois appels vous permettent de passer d'un brief à un site téléchargeable. Remplacez YOUR_API_KEY par une clé du tableau de bord.
1. Démarrer une génération
POST /sites valide votre brief, réserve le prix de génération sur votre solde et répond immédiatement.
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 réponse est 202 Accepted avec le nouveau 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. Interroger le statut
Interrogez GET /sites/{uuid} toutes les 5 à 20 secondes jusqu'à ce que le statut soit done ou error, ou utilisez une URL de callback au lieu de faire du polling.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. Téléchargez les fichiers
Un site terminé se télécharge sous forme de ZIP. Le format est multi ou onepage ; les assets sont intégrés (inline) ou externes.
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"Le même flux en 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"]Authentification
Envoyez une clé API avec chaque requête sauf pour le document OpenAPI. Gardez les clés sur votre serveur ; ne les placez jamais dans le code navigateur ou dans les URLs.
- En-tête : Authorization: Bearer YOUR_API_KEY, ou X-API-Key: YOUR_API_KEY.
- Créez, révoquez et limitez le taux des clés dans le tableau de bord. Les clés peuvent avoir une date d'expiration et une liste blanche d'adresses IP.
- Vous ne voyez que vos propres sites. Un site appartenant à un autre compte retourne 404 not_found.
- Ajoutez ?lang=xx ou Accept-Language pour localiser les messages d'erreur.
Idempotence
Envoyez Idempotency-Key (8–80 caractères : lettres, chiffres, _ et -) sur POST /sites. Répéter la même clé renvoie le site original sans facturer deux fois, donc les réessais après un timeout sont sûrs. Utilisez une nouvelle clé pour réessayer une génération échouée.
Webhooks (callbacks)
Passez callback_url à POST /sites (ou définissez un webhook de compte) et recevez un POST JSON lorsque le travail se termine (site.completed) ou échoue (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-…"
}Lorsque le compte dispose d'un secret webhook, chaque demande porte X-Webhook-Signature : sha256=<hex>, un HMAC-SHA256 du corps brut. Vérifiez-le avant d'analyser le JSON, en utilisant une comparaison en temps constant :
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));Chaque callback est tenté une fois avec un délai d'attente de 10 secondes et n'est pas retenté. Traitez-le comme une notification et réconciliez avec GET /sites/{uuid}. Gérez les répétitions de manière idempotente par uuid et événement. Les cibles en réseau privé sont rejetées.
Erreurs
Chaque réponse utilise une enveloppe. Les erreurs comportent un code stable, un message localisé et, pour les erreurs de validation, le champ en échec.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | Codes d'erreur |
|---|---|
| 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 | Valeur |
|---|---|
| Requêtes par clé | 60 par minute par défaut (configurable par clé, 0 = illimité). Les clés invalides répétées d'une même IP obtiennent un 429 avec Retry-After. |
| Corps de la requête | 2 Mo ; POST /sites avec images de référence jusqu'à 162 Mo ; l'éditeur enregistre jusqu'à 4 Mo. |
| Images de référence | Jusqu'à 12 images PNG, JPEG ou WEBP (base64 ou data URL), au maximum 10 Mo chacune. |
| Contenu de la page de l'éditeur | HTML jusqu'à 500 000 caractères, CSS jusqu'à 100 000. Les scripts et gestionnaires d'événements sont supprimés. |
| Images du site | PNG, JPEG, WEBP ou GIF, 5 Mo chacune, jusqu'à 200 par site. |
| Titre du site | Titre du site 1–200 caractères. |
API Éditeur
Tout ce que fait l'éditeur du tableau de bord est disponible pour vos sites terminés : contenu de la page, plan de la page et des sections, style, titre/thème/Disposition/structure, suivi et images. Les modifications de page remplacent la page ; DELETE restaure la page générée.
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"L'édition nécessite un site complet (409 site_not_ready sinon). Le changement de thème, disposition ou structure sur des pages modifiées renvoie 409 edits_reset_required sauf si reset_edits est vrai. L'édition est gratuite.
Référence des endpoints
Généré à partir du document OpenAPI, il correspond toujours à l'API en direct. Les chemins sont relatifs à l'URL de base.
Compte
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
Catalogue
-
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 et automatisation
-
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.
Éditeur
-
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.
Paiements externes (clés administrateur uniquement)
-
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.
Les descriptions proviennent du document OpenAPI et sont en anglais. Les schémas de requête et de réponse se trouvent dans le fichier de schéma.
Intégrations prêtes à l'emploi
Le kit d'intégration est une petite application PHP avec un formulaire de génération, une interrogation du statut, des conseils pour les callbacks signés et un éditeur visuel complet qui communique avec cette API via un proxy côté serveur. Créez un compte pour obtenir une clé, puis consultez la tarification pour le coût de chaque génération.