Refine site
refine_siteHave Mondovo's AI make changes to an existing site from a natural-language instruction (e.g. "make the hero bigger with a dark background", "change the primary color to navy", "add a testimonials section"). This is the right tool for open-ended design work, or when you cannot see the source. For copy-only changes prefer patch_variation_content, and when this connection holds source:read and you can author the exact change yourself, prefer read_design → update_variation_file — both are instant, deterministic, and land in the same version history as a refinement. Pass image_urls to attach REFERENCE images the change should be modelled on — a screenshot of a layout to match, a mockup, a competitor's section — and say what to do with them in the instruction ("make the hero section match this layout"). They are shown to the model as pictures, so use them whenever the target is easier to show than to describe; a described layout is reproduced far less faithfully than one the model can see. The images are a REFERENCE for the design, not content to insert — to place an actual photo on the page, describe where it goes and pass its url in the instruction. URLs must be on Mondovo storage: call upload_asset first and pass the permanent url it returns. For retry safety, reuse the same optional idempotency_key for one refinement attempt. Returns a job_id immediately; poll get_job every ~10s until its status is "completed" (a refinement typically takes 30-120s). The work runs server-side and completes even if this conversation ends, so a lost connection is not a failed refinement. If the site already has another operation running you get site_busy with that operation's job_id — poll it, then retry. page targets one page by slug — including a PAGE DRAFT's slug (from create_page_draft), which edits the draft and leaves the live page alone. variation_id selects the design to edit. On a design site with several alternatives it is REQUIRED: show the choices from list_variations and let the user choose, rather than assuming the active or first design. On a built or single-design site, omit it for the chosen design. A page draft that lives in a different design is edited with patch_variation_content / update_variation_file instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Slug of the page to change, e.g. "/about", or a page draft's slug from create_page_draft. Omit for the home page. | |
| site_id | Yes | The site ID to refine | |
| user_goal | No | Optional: the user's goal behind this call, in one short sentence of plain words (e.g. "add a page so customers can book tables"). No names, emails or other personal details. | |
| image_urls | No | ||
| instruction | Yes | ||
| variation_id | No | variation_id of the design to change (from list_variations). Required when a design site holds several alternatives; omit on a built or single-design site to use its chosen design. | |
| idempotency_key | No | Optional stable key for one refinement attempt. Reuse it after a timeout to receive the original job instead of queueing a second refinement. |