API 문서
화이트페이지 사이트를 생성하고, 진행 상황을 추적하며, 자신의 코드, 노코드 도구 또는 AI 어시스턴트에 질문하여 파일을 다운로드하세요. 모든 요청은 HTTPS를 통한 JSON 형식입니다.
작동 방식
세 단계, 연결 방법에 상관없이:
- API 키 생성 로그인 후 대시보드의 API 키에서 키를 생성하세요. 계정 비밀번호처럼 작동하므로 비공개로 유지하세요.
- 사이트 요청 제목과 언어를 보내고, 주제, 대상 및 키워드가 마음에 들면 함께 보내세요. 생성 비용이 잔액에서 차감되고 사이트가 구축되기 시작합니다.
- 사이트 수집 보통 몇 분 내에 준비됩니다. 상태를 확인하거나 완료되면 URL을 호출하도록 설정할 수 있으며, 미리 보기, 편집 및 파일 다운로드가 가능합니다.
연결 방법 선택
- 나는 AI 어시스턴트를 사용합니다 클로드, ChatGPT, Cursor 등은 사이트를 생성하고 추적할 수 있습니다.
- 나는 코드를 작성합니다 curl, PHP, Node.js 및 Python 예제와 함께 세 가지 REST 호출.
- 나는 노코드 툴을 사용합니다 Zapier, Make 또는 n8n과 같이 HTTP 요청을 보낼 수 있는 모든 것은 동일한 세 가지 호출을 실행할 수 있습니다.
노코드 도구: HTTP 요청을 보낼 수 있는 모든 도구(Zapier, Make, n8n, 스프레드시트 스크립트)는 동일한 호출을 실행할 수 있습니다. POST /sites는 사이트를 시작하며; GET /sites/{uuid}는 타이머나 callback_url로 완료 시점을 알려줍니다. API 키를 Authorization 헤더에 넣으세요.
핵심 용어
- 사이트
- 모든 페이지를 가진 하나의 생성된 웹사이트입니다. uuid로 식별됩니다.
- 상태
- 빌드 중일 때는 pending, 준비되면 done, 실패 시 error입니다. 실패한 사이트는 자동으로 환불됩니다.
- API 키
- 요청이 귀하의 계정에서 왔음을 증명하는 비밀 문자열입니다. 대시보드에서 키를 생성 및 취소할 수 있습니다.
- 잔액
- 계정 내 선불 잔액입니다. 사이트를 생성하면 생성 비용이 예약됩니다.
- 콜백
- 사이트가 완료되면 호출하는 귀하 소유의 URL로, 지속적으로 확인할 필요가 없습니다.
- 멱등성 키
- 한 요청에 붙이는 라벨로, 두 번 보내도 두 개의 사이트가 생성되거나 요금이 청구되지 않습니다.
AI 어시스턴트와 함께 사용하기
AI 어시스턴트를 연결하고 간단히 물어보세요: "내 치과 클리닉을 위한 사이트를 터키어로 만들어줘." 어시스턴트는 귀하 계정 하에서 동일한 API를 호출합니다. 귀하는 제어권을 유지합니다: 사이트 생성은 잔액을 사용하며, 좋은 어시스턴트는 생성 전에 반드시 물어봅니다.
말할 수 있는 것들
- 내 잔액은 얼마이며, 사이트 하나당 비용은 얼마인가요?
- 어떤 디자인 키트가 베이커리에 적합한가요?
- 조용한 항구 게스트하우스인 알더 하우스의 원페이지 사이트를 영어로 만드세요.
- 내 사이트가 준비되었나요? 미리보기 링크를 보내주세요.
MCP(Claude, Cursor 등)와 연결하기
MCP는 보조 도구들이 외부 도구를 호출할 때 사용하는 오픈 스탠다드입니다. 보조 도구에 MCP URL을 지정하고 API 키를 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
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은 mcp-remote 브리지를 통해 원격 서버에 접속하며, Node.js가 필요합니다..
ChatGPT (사용자 지정 GPT)
- ChatGPT에서 GPT를 만든 후, 설정을 열고 새 작업 생성을 선택하세요.
- URL에서 가져오기를 선택하고 https://whitepagekit.com/api/v1/openapi.json?profile=assistant을 붙여넣으세요. 이 축소된 스키마는 6개의 보조 도구만 포함합니다.
- 인증에서 API 키를 선택하고 인증 유형을 Bearer로 설정한 뒤 API 키를 붙여넣으세요.
- ChatGPT는 잔액을 소모하는 변경 요청을 확인하도록 요구하여 사용자가 비용 발생에 대한 통제권을 유지하게 합니다.
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantOpenAI API (MCP 도구)
Responses API는 MCP URL을 원격 도구로 사용할 수 있습니다. require_approval은 사람이 개입하도록 합니다.
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)사용자 도구 루프 (함수 호출)
모델 루프를 직접 실행하는 경우, 준비된 도구 스키마를 가져와 각 도구 호출을 해당 REST 엔드포인트와 연동하여 실행하세요. 형식: openai (Responses API), openai-chat, anthropic, mcp.
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcp6가지 도구
| 도구 | 무엇을 하는가 | REST 호출 | 비용 |
|---|---|---|---|
get_account |
잔액과 사이트 하나당 비용을 보여줍니다. | GET /me |
무료 |
list_languages |
사이트를 작성할 수 있는 언어 목록입니다. | GET /languages |
무료 |
list_themes |
주제 또는 스타일별로 디자인 키트를 검색합니다. | GET /themes |
무료 |
create_site |
사이트 생성을 시작하고 생성 비용을 잔액에서 차감합니다. | POST /sites |
잔액 사용 |
get_site |
사이트 하나를 보여줍니다: 진행 상황, 미리보기 링크 및 다운로드 링크. | GET /sites/{uuid} |
무료 |
list_sites |
내 사이트 목록을 최신순으로 보여줍니다. | GET /sites |
무료 |
이 문서를 어떤 AI에게든 제공하세요
이 페이지는 평범한 Markdown 형태로도 제공되어, 채팅에 붙여넣거나 코딩 보조 도구에 전달하기에 이상적입니다:
Markdown
https://whitepagekit.com/api/v1/docs.md붙여넣을 수 있는 프롬프트
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.안전성 및 비용
- create_site만 잔액을 사용합니다. 나머지 다섯 도구는 읽기 전용입니다.
- 어시스턴트용으로 별도의 키를 사용하세요. 대시보드에서 만료일과 속도 제한을 설정하고 언제든지 취소할 수 있습니다.
- 어시스턴트는 사이트를 삭제하거나 설정을 변경하거나 결제를 건드릴 수 없습니다: 해당 경로들은 도구로 노출되지 않습니다.
- create_site에서 idempotency_key를 설정하여 재시도 시 이중 청구를 방지하세요. 실패한 생성은 환불됩니다.
- 페이지 편집, 참조 이미지 및 ZIP 다운로드는 REST API와 대시보드에 유지됩니다.
빠른 시작
세 번의 호출로 요약에서 다운로드 가능한 사이트까지 진행합니다. YOUR_API_KEY를 대시보드에서 받은 키로 교체하세요.
1. 생성 시작
POST /sites는 요약을 검증하고 잔액에서 생성 비용을 예약하며 즉시 응답합니다.
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"}'응답은 새 사이트와 함께 202 승인입니다:
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. 상태 확인 (폴링)
GET /sites/{uuid}를 약 5~20초 간격으로 폴링하여 상태가 완료 또는 오류인지 확인하거나, 폴링 대신 콜백 URL을 사용할 수 있습니다.
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. 파일 다운로드
완료된 사이트는 ZIP 파일로 다운로드됩니다. format은 multi 또는 onepage; assets는 inline 또는 external입니다.
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"코드에서 같은 흐름
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"]인증
OpenAPI 문서 외의 모든 요청에 API 키를 전송하세요. 키는 서버에 보관하고 브라우저 코드나 URL에 절대 넣지 마세요.
- 헤더: Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY.
- 대시보드에서 키를 생성, 취소 및 속도 제한할 수 있습니다. 키에는 만료 날짜와 IP 허용 목록이 설정될 수 있습니다.
- 본인 소유의 사이트만 볼 수 있습니다. 다른 계정 소유 사이트는 404 not_found를 반환합니다.
- ?lang=xx 또는 Accept-Language를 추가하여 오류 메시지를 현지화하세요.
멱등성
POST /sites에 Idempotency-Key(8~80자: 영문자, 숫자, _ 및 -)를 보내세요. 동일 키 반복 시 원본 사이트를 반환하고 중복 요금을 청구하지 않으므로 시간 초과 후 재시도가 안전합니다. 실패 생성 재시도 시 새 키를 사용하세요.
웹후크(콜백)
POST /sites에 callback_url을 전달하거나 계정 웹후크를 설정하면 작업이 완료(site.completed)되거나 실패(site.failed)할 때 JSON POST를 하나 받습니다.
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-…"
}계정에 웹후크 비밀키가 있을 경우, 모든 요청에는 X-Webhook-Signature: sha256=<hex>가 포함되며, 이는 원본 본문의 HMAC-SHA256입니다. JSON을 파싱하기 전에 상수 시간 비교를 사용하여 이를 검증하세요:
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));각 콜백은 10초 타임아웃으로 한 번 시도되며 재시도되지 않습니다. 이를 알림으로 처리하고 GET /sites/{uuid}로 조정하세요. uuid 및 이벤트별로 반복을 멱등성 있게 처리하세요. 사설 네트워크 대상은 거부됩니다.
오류
모든 응답은 엔벨로프 형식을 사용합니다. 오류에는 안정적인 코드, 현지화된 메시지와 검증 오류의 경우 실패한 필드가 포함됩니다.
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | 오류 코드 |
|---|---|
| 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 |
제한
| 제한 | 값 |
|---|---|
| 키별 요청 수 | 기본적으로 분당 60회(키별로 구성 가능, 0 = 무제한). 한 IP에서 반복적으로 유효하지 않은 키가 사용되면 429 및 Retry-After가 발생합니다. |
| 요청 본문 | 2MB; 참조 이미지를 포함하는 POST /sites는 최대 162MB; 편집기 저장은 최대 4MB. |
| 참조 이미지 | 최대 12개 PNG, JPEG 또는 WEBP 이미지(base64 또는 데이터 URL), 각각 최대 10MB. |
| 편집기 페이지 내용 | HTML 최대 500,000자, CSS 최대 100,000자. 스크립트 및 이벤트 핸들러는 제거됩니다. |
| 사이트 이미지 | PNG, JPEG, WEBP 또는 GIF, 각각 5MB, 사이트당 최대 200개. |
| 사이트 제목 | 사이트 제목 1~200자. |
편집기 API
대시보드 편집기에서 하는 모든 작업이 완료된 사이트에 제공됩니다: 페이지 콘텐츠, 페이지 및 섹션 계획, 스타일, 제목/테마/레이아웃/구조, 추적 및 이미지. 페이지 편집은 페이지를 교체하며; DELETE는 생성된 페이지를 복원합니다.
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"편집에는 완료된 사이트가 필요합니다 (그렇지 않으면 409 site_not_ready). 편집된 페이지 위에 테마, 레이아웃 또는 구조를 변경하면 reset_edits가 true가 아니면 409 edits_reset_required가 반환됩니다. 편집은 무료입니다.
엔드포인트 참조
OpenAPI 문서에서 생성되므로 항상 라이브 API와 일치합니다. 경로는 기본 URL에 상대적입니다.
계정
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
카탈로그
-
GET
/languagesList enabled supported languages
-
GET
/themesList site themes
-
GET
/layoutsList enabled layouts
사이트
-
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 및 자동화
-
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.
편집기
-
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.
외부 결제 (관리자 키 전용)
-
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.
설명은 OpenAPI 문서에서 가져오며 영어로 되어 있습니다. 요청 및 응답 스키마는 스키마 파일에 있습니다.
기성 통합
통합 키트는 생성기 양식, 상태 폴링, 서명된 콜백 안내 및 이 API와 통신하는 전면 시각 편집기를 포함하는 작은 PHP 응용 프로그램입니다. 계정을 만들어 키를 받은 후 각 생성 비용에 대한 가격 정보를 확인하세요.