POST /v1/sites

Create a new site. Warpweb researches the business, generates copy and design, and deploys to a free subdomain. Returns immediately with a site_id; the actual build runs asynchronously and typically completes in 60-120 seconds.

Cost: ~~150 credits (~~$1.50). Charged on successful deploy. Failed builds don’t deduct.

Request

curl -X POST https://api.warpweb.ai/v1/sites \
  -H "Authorization: Bearer wpwb_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Brookside Plumbing",
    "business_location": "Austin, TX",
    "business_type": "Residential plumbing services",
    "contact_email": "owner@brooksideplumbing.com"
  }'

Body

Field	Type	Required	Description
`business_name`	string	yes	The business as customers know it. Used for branding and copy.
`business_location`	string	yes	City + state/region. Drives local SEO, “areas we serve” content, and example testimonials.
`business_type`	string	yes	Free-text description of what the business does. The more specific, the better the generated copy.
`contact_email`	string	yes	Where the contact form delivers if no webhook is configured. Used for the operator notification on first deploy.
`template_hint`	string	no	Optional design hint: `professional`, `playful`, `bold`, `minimal`, `classic`. Default: auto-selected from business type.
`metadata`	object	no	Arbitrary JSON you can attach to the site for your own tracking. Returned on `GET /v1/sites/:id`. Max 4KB.

Response

{
  "site_id": "site_8f3c2a1b-5d47-4c9e-b820-1f8a3e7d9c4f",
  "status": "building",
  "created_at": "2026-05-17T14:23:11Z"
}

Field	Description
`site_id`	Opaque identifier. Use this for all subsequent calls.
`status`	Always `building` on initial response. Poll `GET /v1/sites/:id` for progress.
`created_at`	ISO 8601 UTC.

Lifecycle

building — research + design + copy generation in progress.
deploying — content generated, Cloudflare Pages deploy in flight.
live — deployed_url is now reachable.
failed — build error. The response includes failed_reason. No credits charged.

If you’ve configured a revision-status webhook, you’ll receive a site.build_complete event when the site goes live instead of polling.

Errors

Status	Error	Cause
400	`missing_required_field`	`business_name`, `business_location`, `business_type`, or `contact_email` is missing.
402	`insufficient_credits`	Account balance below the build cost. Top up at app.warpweb.ai/billing.
422	`unprocessable_business`	Business description was flagged as low-information, adult content, or otherwise unbuildable. Returns suggested edits.
429	`rate_limited`	See Authentication → Rate limits.

Overview GET /v1/sites