Aller au contenu
White page Kit
Français

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 :

  1. 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.
  2. 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.
  3. 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

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é)

  1. Dans ChatGPT, créez un GPT, ouvrez Configurer et choisissez Créer une nouvelle action.
  2. 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.
  3. Sous Authentification, choisissez Clé API, réglez le Type d'authentification sur Bearer et collez votre clé API.
  4. 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=assistant

API 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, mcp

Les six outils

Les 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.md

Un 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" }
  }
}
Erreurs
HTTPCodes 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

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 /me

    Get the authenticated account

  • GET /transactions

    List account balance transactions

Catalogue

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

Sites

  • GET /sites

    List the authenticated account's sites

  • POST /sites

    Start 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}/download

    Download a completed site archive

IA et automatisation

  • GET /ai-tools

    Function-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.md

    Documentation 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 /mcp

    Model 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}/editor

    Load 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}/editor

    Save 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}/editor

    Restore a page's generated content — Discards the page's saved edits. Returns the regenerated page.

  • GET /sites/{uuid}/editor/canvas

    Get 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}/pages

    Get 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}/pages

    Save 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}/style

    Get style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.

  • POST /sites/{uuid}/style

    Save or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.

  • GET /sites/{uuid}/design

    Get 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}/design

    Change 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}/tracking

    Get tracking settings

  • POST /sites/{uuid}/tracking

    Save 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}/media

    List uploaded site images

  • POST /sites/{uuid}/media

    Upload 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-sites

    List 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-sites

    Register 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 /payments

    List external orders owned by the admin API account

  • POST /payments

    Create 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}/cancel

    Cancel 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}/approve

    Approve 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.