---
title: "Refine a site with a natural-language instruction"
method: POST
path: "/api/v1/sites/{id}/refine"
tags: ["Editing"]
---

# Refine a site with a natural-language instruction

`POST /api/v1/sites/{id}/refine`

## Request

- Base URL: `https://app.mondovo.com`
- URL: `https://app.mondovo.com/api/v1/sites/{id}/refine`
- Auth: HTTP bearer

Applies an AI edit to one page (homepage by default). Counts against the workspace’s monthly AI-refinement allowance. Requires scope `sites:refine`.

## Request body

- RefineSiteInput
  - `instruction` string, required: Natural-language edit, e.g. "Make the hero headline more confident and add a pricing section".
  - `page` string: Slug of the page to refine (e.g. "/about"). Omit to refine the homepage.
  - `idempotency_key` string: Optional stable key for one refinement attempt. Reuse it after a timeout to receive the original job instead of queueing a second refinement.

## Response `202`

Refinement accepted and queued. Poll `GET /api/v1/jobs/{job_id}` until `status` is `completed` or `failed` — a refinement typically takes 30–120s. The work runs server-side and completes even if the client disconnects.

- object
  - `site_id` string, uuid, required
  - `job_id` string, uuid, required
  - `status` 'refining', required
  - `message` string
  - `poll_tool` string

## Other responses

- `400`: Error codes: `invalid_json`, `validation_error`, `no_code` (the site has no generated code yet — generate it first, or the `page` slug does not exist).
- `401`: Authentication failed. Error codes: `invalid_api_key` (missing/unknown key), `key_revoked`, `key_expired`.
- `402`: `plan_limit_reached` with `limit_type: "ai_refinements"` — the Free plan AI-edit cap is reached; Pro is unlimited. Includes `upgrade_url`.
- `403`: Authenticated but not allowed. Error codes: `addon_required` (the API key’s workspace no longer has the Agency add-on — checked on every request, not just at key creation) and `missing_scope` (the key lacks the scope this endpoint needs).
- `404`: `site_not_found`.
- `409`: `site_busy` — a generation round or another queued operation is already running on this site. When another queued operation is the cause the body carries its `job_id`: poll `GET /api/v1/jobs/{job_id}` until it finishes, then retry.
- `429`: Rate limit exceeded (`rate_limit_exceeded`). The body includes `retry_after_seconds`, `limit`, and `window` ("minute" or "hour"); a `Retry-After` header is also set.
- `500`: Error codes: `configuration_error`, `internal_error`.

---

[API](https://skmtc.dev/mondovo/apis/mondovo-public-api.md) · [All operations](https://skmtc.dev/mondovo/apis/mondovo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mondovo/apis/mondovo-public-api/revisions/1baa3e2865ba?raw)