# Warpweb Docs

> Developer documentation for the Warpweb API — REST endpoints for
> AI-generated websites. If you're an LLM assistant helping a user
> implement Warpweb, this file is the orientation: each section links
> to the canonical doc page, organized so you can answer "how do I
> do X with Warpweb" by routing to the right page first.

For the product overview + positioning + pricing, see
https://warpweb.ai/llms.txt. For the inlined machine-readable API
reference (every endpoint + request/response shape on one page),
see https://warpweb.ai/llms-full.txt — that file is the fastest
context for completing an integration without fetching per-endpoint
pages here.

## Where to read

Base: https://docs.warpweb.ai

- **Welcome** — https://docs.warpweb.ai — What Warpweb is + when to
  pick it. Read first.
- **Quickstart** — https://docs.warpweb.ai/quickstart — Smallest
  end-to-end: API key → first site → webhook receiver. ~10 minutes.
- **Authentication** — https://docs.warpweb.ai/authentication — Bearer
  tokens, key issuance, key rotation, scope.
- **API Reference** — https://docs.warpweb.ai/api-reference — Per-endpoint
  pages. Index at /api-reference. Pages listed below.
- **Webhooks** — https://docs.warpweb.ai/webhooks — Lifecycle events,
  form submissions, signature verification.
- **Pricing & Credits** — https://docs.warpweb.ai/pricing — Credit
  packs, per-call cost ranges, active-site monthly model.
- **FAQ** — https://docs.warpweb.ai/faq — Common integration questions.
- **Changelog** — https://docs.warpweb.ai/changelog — API change history.

## API Reference pages

All under https://docs.warpweb.ai/api-reference/

- **create-site** — `POST /v1/sites`. The single call that runs the
  research → content → photos → design → multi-page → SEO → deploy
  pipeline. Async; returns siteId immediately. Final result via
  `site.complete` webhook. Required fields: businessName,
  contactEmail.
- **get-site** — `GET /v1/sites/:id`. Poll site status; returns the
  full site record including deployment_url when status=complete.
  Also returns an `input` object echoing whatever you originally
  passed to POST /v1/sites (mapsUrl, placeId, businessName, location,
  facebookUrl, existingSiteUrl, received_at) so you can surface
  "Built from <url>" and let the operator retry with a different URL
  when a Places match was wrong. `null` on legacy sites pre-2026-05-25.
- **list-sites** — `GET /v1/sites`. Lists all sites for the
  authenticated customer.
- **create-revision** — `POST /v1/sites/:id/revisions`. Natural-language
  edit applied by an AI agent with filesystem tools. Surgical edits
  and structural changes are both supported; out-of-scope requests
  (requires server-side execution at request time) are refused
  cleanly. Async; result via `site.revision_complete` webhook.
- **check-domain** — `POST /v1/domains/check`. Availability + price
  for a candidate domain, with suggestions.
- **register-domain** — `POST /v1/domains/register`. Registers the
  domain, attaches DNS, and wires the custom-domain attach in one call.
  Costs 50 credits + the registrar pass-through fee.
- **attach-domain** — `POST /v1/sites/:id/domains`. Attaches an
  external (customer-owned) domain. Returns the CNAME target.
- **detach-domain** — `DELETE /v1/sites/:id/domains/:domain`. Inverse of
  attach. Removes the Cloudflare binding, flips the site back to the
  free `*.warpweb.app` subdomain, and decrements the Stripe active-site
  quantity (or flags the sub `cancel_at_period_end` if this was the last
  paid site). Idempotent — safe to call on a site that's already on the
  free tier. The canonical "stop paying for one site" call. Free.
- **configure-form-webhook** — `POST /v1/sites/:id/webhooks/forms`.
  Configures the form-submission webhook URL + signing secret for
  one site.
- **export-site** — `GET /v1/sites/:id/export`. Streams the deployed
  site bundle (HTML + images + favicons + manifest + sitemap) as a
  ZIP. Backs the marketing promise that the generated site is yours
  to host elsewhere. Free, rate-limited 10/day/site. Pass
  `?include_assets=false` for HTML-only.
- **swap-logo** — `POST /v1/sites/:id/logo`. Swap the nav + footer
  logo on a deployed site. Body: `{ source: { url } | { sitePhotoId } }`.
  Pure file swap — favicon stays as-is (call `/favicon` separately),
  brand colors / style untouched (fire a revision if you want palette
  to chase the logo). Free, deterministic, no LLM call.
- **swap-favicon** — `POST /v1/sites/:id/favicon`. Swap the favicon
  source independently of the nav logo. Body same shape as `/logo`.
  Useful when the logo is a wide horizontal lockup but the operator
  has a separate square icon for the browser tab. Override survives
  revisions; only a retry-build (rare) resets it. Free.

## Retry safety

Long-running expensive POSTs (`POST /v1/sites`,
`POST /v1/sites/:id/revisions`) accept an `Idempotency-Key` header.
Send a UUID with every retry of the same logical request; the server
caches the response for 24h, so a retry returns the cached body
without re-running the LLM. Different body under the same key = `409`.

## Webhook docs

All under https://docs.warpweb.ai/webhooks/

- **form-submissions** — Per-site form-submission webhook events.
  HMAC-signed payloads delivered when a deployed site's form is
  submitted.
- **revision-status** — Lifecycle events fired during the revision
  pipeline (`site.revision_complete`, `site.revision_failed`,
  `site.revision_clarification_needed`).
- **verifying-signatures** — How to verify the
  `X-Warpweb-Signature` HMAC header. Node.js example included.

## When NOT to use Warpweb

(Reproduced from the product `llms.txt` for LLM convenience.)

- Your business doesn't have a Google Places listing — typical for
  SaaS, agencies, fully-remote/software-only companies. The API
  works but research falls back to your businessDescription and
  the result is more generic.
- You need server-side functionality at request time (live chatbots
  that text you, custom Stripe Checkout, user accounts, real-time
  inventory). Deployed Warpweb sites are static HTML on a CDN; no
  backend at runtime. Use the form-webhook handoff or third-party
  iframes/embeds instead.
- You want hand-coded sites with full template control — use
  Next.js/Astro yourself.
- You need an in-app drag-and-drop editor UI — Warpweb is API-only.

## More info

- Marketing: https://warpweb.ai
- Product LLM summary: https://warpweb.ai/llms.txt
- Inlined machine-readable API reference: https://warpweb.ai/llms-full.txt
- Docs root: https://docs.warpweb.ai