본문으로 건너뛰기
White page Kit
한국어

API 문서

화이트페이지 사이트를 생성하고, 진행 상황을 추적하며, 자신의 코드, 노코드 도구 또는 AI 어시스턴트에 질문하여 파일을 다운로드하세요. 모든 요청은 HTTPS를 통한 JSON 형식입니다.

작동 방식

세 단계, 연결 방법에 상관없이:

  1. API 키 생성 로그인 후 대시보드의 API 키에서 키를 생성하세요. 계정 비밀번호처럼 작동하므로 비공개로 유지하세요.
  2. 사이트 요청 제목과 언어를 보내고, 주제, 대상 및 키워드가 마음에 들면 함께 보내세요. 생성 비용이 잔액에서 차감되고 사이트가 구축되기 시작합니다.
  3. 사이트 수집 보통 몇 분 내에 준비됩니다. 상태를 확인하거나 완료되면 URL을 호출하도록 설정할 수 있으며, 미리 보기, 편집 및 파일 다운로드가 가능합니다.

연결 방법 선택

노코드 도구: 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)

  1. ChatGPT에서 GPT를 만든 후, 설정을 열고 새 작업 생성을 선택하세요.
  2. URL에서 가져오기를 선택하고 https://whitepagekit.com/api/v1/openapi.json?profile=assistant을 붙여넣으세요. 이 축소된 스키마는 6개의 보조 도구만 포함합니다.
  3. 인증에서 API 키를 선택하고 인증 유형을 Bearer로 설정한 뒤 API 키를 붙여넣으세요.
  4. ChatGPT는 잔액을 소모하는 변경 요청을 확인하도록 요구하여 사용자가 비용 발생에 대한 통제권을 유지하게 합니다.

Schema URL

https://whitepagekit.com/api/v1/openapi.json?profile=assistant

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

6가지 도구

6가지 도구
도구 무엇을 하는가 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 /me

    Get the authenticated account

  • GET /transactions

    List account balance transactions

카탈로그

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

사이트

  • 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 및 자동화

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

편집기

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

외부 결제 (관리자 키 전용)

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

설명은 OpenAPI 문서에서 가져오며 영어로 되어 있습니다. 요청 및 응답 스키마는 스키마 파일에 있습니다.

기성 통합

통합 키트는 생성기 양식, 상태 폴링, 서명된 콜백 안내 및 이 API와 통신하는 전면 시각 편집기를 포함하는 작은 PHP 응용 프로그램입니다. 계정을 만들어 키를 받은 후 각 생성 비용에 대한 가격 정보를 확인하세요.