API Reference

Base URL: https://api.warpweb.ai. All requests require Bearer authentication. All bodies are JSON.

Endpoints

Discovery

Sites

Domains

Webhooks (per-site + customer-level)

See Webhooks for the event catalog and payload shapes.

Common conventions

IDs. Site IDs and revision IDs are UUIDs. Always treat them as opaque strings.

Field naming varies by surface. Field naming follows whichever surface you’re touching — see the per-endpoint Request and Response sections, which are authoritative. (Quickstart Step 3 includes a short cheat sheet for the camelCase/snake_case split when you chain create → get.)

Timestamps. ISO 8601 UTC, e.g. 2026-05-17T14:23:11Z.

Async operations. POST /v1/sites and POST /v1/sites/:id/revisions return immediately with an id and status: "generating" / status: "pending". The final result arrives via lifecycle webhook (preferred) or by polling GET /v1/sites/:id.

Idempotency.

• POST /v1/sites/:id/refresh — idempotent (safe to retry any number of times).
• POST /v1/sites/:id/webhooks/forms with the same webhook_url — idempotent; won’t re-issue the secret unless rotate_secret: true.
• POST /v1/sites/:id/domains (external attach) — idempotent at the CDN layer; safe to retry.
• POST /v1/sites — not idempotent; each call kicks off a fresh build. Dedupe on your side by placeId (or mapsUrl, normalized) if you need it.
• Webhook deliveries — dedupe on event_id (UUID, stable across retries).

Errors. Non-2xx responses return JSON with an error field:

{
  "error": "Site not found"
}

See Error shapes for the full envelope reference (optional hint, reason, suggestion, quota fields and which endpoints emit them).

Credit-eligible operations deduct from your balance on success. Failed operations don’t charge. See Pricing & Credits for the cost table.