Vai al contenuto
White page Kit
Italiano

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:

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

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)

  1. In ChatGPT crea un GPT, apri Configura e scegli Crea nuova azione.
  2. 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.
  3. Sotto Autenticazione scegli Chiave API, imposta Tipo di autenticazione su Bearer e incolla la tua chiave API.
  4. 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=assistant

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

I sei strumenti

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

Un 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" }
  }
}
Errori
HTTPCodici 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

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

    Get the authenticated account

  • GET /transactions

    List account balance transactions

Catalogo

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

Siti

  • 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

AI e automazione

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

Editor

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

Pagamenti esterni (solo chiavi amministratore)

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

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.