POST /v1/sites/:id/revisions

Request a revision to a deployed site in plain English. An AI agent with filesystem tools applies your requested change — small edits and structural changes are both supported. Returns immediately; the agent runs asynchronously and the final result arrives via the site.revision_complete (or site.revision_failed) lifecycle webhook.

Cost: ~20–100 credits, billed against actual usage at the end of the revision. Failed revisions don’t charge. Exact cost lands in usage.cost_usd on the site.revision_complete webhook.

Request

curl -X POST https://api.warpweb.ai/v1/sites/8f3c2a1b/revisions \
  -H "Authorization: Bearer wwk_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the hero headline to emphasize 24/7 emergency service. Add a phone number to the header."
  }'

Body

Retry safety: Idempotency-Key header

Same pattern as POST /v1/sites. Send Idempotency-Key: <uuid> to make retries safe — a duplicate request with the same key + same body returns the cached response without re-running the LLM. Different body with the same key returns 409. Cached for 24h.

Response

{
  "revisionId": "2a8f1c3b-4e92-4d51-a724-9f3e8d2c1b6a",
  "status": "pending",
  "queue_position": 0,
  "queue_total": 1
}

usage lands on the lifecycle webhook, not this response. Revisions run asynchronously inside a per-site FIFO queue. The final usage aggregate ({ credits_charged, tokens_in, tokens_out, cost_usd }) ships on the site.revision_complete lifecycle webhook payload as the usage field alongside tool_breakdown + billing. See Error shapes → defensive parsing for the recommended client handling.

Revisions on the same site run sequentially — at most one runs at a time, with up to 2 more waiting. If a third is queued and you try to add a fourth, you’ll get 429 queue_full (see Errors below). Different sites run in parallel.

The deployed URL updates in place when the revision lands. For a reliable signal, configure a lifecycle webhook and listen for site.revision_complete.

Out-of-scope refusals

Some requests can’t be satisfied because deployed sites are static — there’s no server running per-request behind the site. If you ask for something that requires server-side logic (a live chatbot, custom Stripe Checkout server code, user accounts, real-time inventory), the agent refuses up front with 422:

{
  "error": "out_of_scope",
  "reason": "Requires server-side execution at request time. Deployed sites are static HTML on a CDN.",
  "suggestion": "I can add a 'Contact us' form that posts to your form_webhook_url — you handle the dispatch on your end with the tooling of your choice."
}

The suggestion field is the customer-facing alternative — typically a form-webhook-based pattern that achieves the same business goal. A site.revision_failed webhook with reason: "out_of_scope" is also fired so your server has ground truth for the next chat turn.

Field semantics differ between the HTTP body and the webhook. On the 422 body above, reason holds the human-readable explanation. On the corresponding site.revision_failed webhook payload, reason holds the machine-readable code ("out_of_scope") and reason_detail holds the human-readable explanation. If your code path reads both, branch by surface.

See FAQ → What’s not supported for the full list of static-deploy limits.

Errors

See Error shapes for the canonical envelope and a note on how reason is overloaded between the 422 body and the site.revision_failed webhook payload.

Writing good prompts

The agent works best when you’re concrete about what you want changed, not how:

• Good: “Move the testimonials section above the services list, and add a 4th testimonial from a customer named Maria.”
• Good: “Make the hero photo darker so the white text reads better.”
• Good: “Add an FAQ section with these questions: What areas do you serve? Are you licensed? Do you offer emergency service?”
• Less good: “Make it better.” (Too vague — the agent has to guess.)

You can iterate. Send another revision call with follow-up instructions any time.