POST /v1/sites

Create a new site. Warpweb researches the business, generates copy and design, and deploys to a free *.warpweb.app subdomain. Returns immediately with a siteId; the build runs asynchronously and the final result is delivered via the site.complete (or site.failed) lifecycle webhook.

Cost: ~200–500 credits, billed against actual usage at the end of the build. Most builds land near 300; the high end (500) hits when the business has 200+ Google reviews and a lot of photos to process. Failed builds don’t charge. The exact cost lands in usage.cost_usd on the site.complete webhook.

Request

curl -X POST https://api.warpweb.ai/v1/sites \
  -H "Authorization: Bearer wwk_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mapsUrl": "https://maps.app.goo.gl/abc123"
  }'

Resolution priority. The handler picks the business identifier in this order: placeId > mapsUrl > businessName + businessLocation. Pass whichever you have — extra fields are ignored when a higher-priority one is present.

Retry safety: Idempotency-Key header

Builds are expensive (~$1–5 of LLM spend). To make retries safe — your client times out, your job runner re-fires, etc. — send an Idempotency-Key header on the request:

curl -X POST https://api.warpweb.ai/v1/sites \
  -H "Authorization: Bearer wwk_<your-key>" \
  -H "Idempotency-Key: 8e7b1c2d-...-your-uuid" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

The server hashes (customer_id, route, body, idempotency_key) and caches the response for 24h. A second request with the same key + same body returns the exact same response without re-running the build. Different body with the same key returns 409 conflict so you can’t accidentally swap content under a key you’ve used.

Recommended client pattern: generate a UUID once when the operator-facing action starts, send it on every retry. Keys are scoped per customer + route, so safe to use the same UUID across endpoints.

Body

share.google URLs are rejected

Warning. share.google/* short URLs are explicitly blocked at the handler with a 400. They require a JavaScript-driven redirect that Google’s bot detection consistently blocks from datacenter IPs (verified across stealth + text-search fallbacks). The canonical google.com/maps/place/<name>/@<lat>,<lng>/... URL always resolves; the maps.app.goo.gl/... short link does too.

Fix on the operator side: open the share.google/... link in any browser, wait for it to land on the canonical Maps URL, then paste that. Or skip the URL entirely and pass placeId (from POST /v1/businesses/search) or businessName + businessLocation.

The 400 response for this case has a hint field with the recovery path inline — surface it in your UI rather than your own copy:

{
  "error": "share.google/* short URLs are not supported. Open the link in a browser, wait for it to land on the canonical google.com/maps/place/... URL, then paste that URL instead. (Or pass placeId / businessName directly.)",
  "hint": "Google's bot detection blocks server-side resolution of share.google links from datacenter IPs. The canonical /maps/place/<name>/@<lat>,<lng>/... URL always works."
}

The same { error, hint } envelope is also returned when a non-share.google mapsUrl resolves to null AND the URL doesn’t carry a derivable business name in its /place/<name>/ segment. See Error shapes for the canonical envelope across endpoints.

Response

{
  "siteId": "8f3c2a1b-5d47-4c9e-b820-1f8a3e7d9c4f",
  "status": "generating",
  "slug": "brookside-plumbing-a1b2c3"
}

usage lands on the lifecycle webhook, not this response. The build runs asynchronously — token + cost data isn’t available at POST time. The final usage aggregate ({ credits_charged, tokens_in, tokens_out, cost_usd }) ships on the site.complete lifecycle webhook payload and is also queryable via GET /v1/sites/:id once the build lands. See Error shapes → defensive parsing for the recommended client handling.

Status lifecycle

If you’ve configured a customer-level lifecycle webhook, you’ll receive a site.complete event when the site goes live — no polling required.

Errors