---
title: "Create a site from a structured brief"
method: POST
path: "/api/v1/sites"
tags: ["Sites"]
---

# Create a site from a structured brief

`POST /api/v1/sites`

## Request

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

Creates a site and starts generation in the background (typically ~60s). Returns `202` immediately; poll `GET /api/v1/sites/{id}` until `status` is `ready`. Requires scope `sites:create`.

## Request body

- CreateSiteInput
  - `name` string, required: Business / site name.
  - `platform_gallery_use` 'confirmed' | 'declined': Explicit permission to use real Mondovo template-gallery captures. Omit or set "declined" to keep gallery sourcing off.
  - `brand_id` string, uuid: Optional existing Brand Studio brand to link. Must belong to your organization. Omit to create a normal unlinked site.
  - `business` object
    - `industry` string
    - `location` string
    - `description` string
    - `services` string[]
    - `target_audience` string
    - `unique_selling_points` string[]
    - `tone_of_voice` string
    - `contact_email` string, email
    - `contact_phone` string
    - `social_links` object: Map of platform name to profile URL.
  - `design` object: Design direction. Unknown extra keys (e.g. "vibe", "typography") are accepted and folded into the creative brief.
    - `style` string
    - `creative_direction` string: The complete freeform visual direction; preserved verbatim in the generation brief.
    - `color_palette` object
      - `primary` string
      - `secondary` string
      - `accent` string
    - `mood` string
    - `sections` string[]: Homepage sections to include, e.g. ["hero","services","testimonials","contact"].
    - `references` string: Free-text style references.
    - `logo_url` string, uri
    - `reference_images` string[]: HTTPS screenshots used as DESIGN references (palette/typography/rhythm), not content to render.
    - `reference_fidelity` 'inspire' | 'replicate': How faithfully to honor reference_images: "replicate" recreates the reference’s structure; "inspire" (default) adapts it.
    - `source_url` string, uri: HTTPS URL of a live site to capture and use as the design source. Non-HTTPS and private hosts are rejected.
    - `source_copy` 'rewrite' | 'preserve': With source_url: "rewrite" (default) writes fresh copy from your business details; "preserve" keeps the source wording.
  - `content` object: Seed content. Unknown extra keys are passed through to the site content.
    - `headline` string
    - `tagline` string
    - `about` string
    - `testimonials` object[]
      - `name` string
      - `text` string, required
      - `rating` number
      - `role` string
    - `services` object[]
      - `name` string, required
      - `description` string
      - `price` string
      - `icon` string
    - `team` object[]
      - `name` string, required
      - `role` string
      - `bio` string
      - `image_url` string, uri
    - `faq` object[]
      - `question` string, required
      - `answer` string, required
  - `pages` string[]: Page names to create, e.g. ["home","about","contact"]. Omit to let Mondovo plan the site structure.
  - `goal` string: The site’s primary conversion objective (e.g. "book a consultation"). Drives hero CTA and section selection. Omitted → inferred.
  - `idempotency_key` string: Stable key for this creation attempt. Retrying a timed-out create with the SAME value returns the site the first attempt made instead of creating a duplicate. Use a fresh value (e.g. a UUID) per new site.

## Response `200`

Idempotent replay: a previous call with the same `idempotency_key` already created this site — that site is returned instead of a duplicate.

- Site
  - `site_id` string, uuid, required
  - `name` string, required
  - `status` 'generating' | 'refining' | 'ready' | 'publishing' | 'published' | 'publish_held' | 'error', required: "publish_held": the last publish crashed or rendered blank when loaded in a browser before going live, so it was not made live; deployment_url (if any) still serves the previous version. See publish_message.
  - `publish_message` string: Plain-language reason the last publish was held. Present only when status is "publish_held".
  - `generation_progress` number: 0-100 while status is "generating".
  - `generation_progress_message` string: Human-readable progress note while generating.
  - `preview_url` string, uri: Shareable public preview link (no login required). Omitted when previews are disabled.
  - `editor_url` string, uri: Deep link into the Mondovo editor (requires login). Omitted while generating or errored.
  - `deployment_url` string, uri: Live URL once published.
  - `pages` string[]: Slugs of the site’s pages (e.g. "/", "/about"). Omitted before generation completes.
  - `error_message` string: Present only when status is "error".
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `202`: Site created; generation started.
- `400`: Error codes: `invalid_json`, `validation_error` (with `details[]`), `invalid_brand`.
- `401`: Authentication failed. Error codes: `invalid_api_key` (missing/unknown key), `key_revoked`, `key_expired`.
- `402`: `plan_limit_reached` with `limit_type: "draft_sites"` — the workspace is at its draft-site limit. Includes `current`, `maximum`, `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).
- `409`: Error codes: `duplicate_request` (a create with this `idempotency_key` is still running) or `generation_conflict` (generation already in progress).
- `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`: Unexpected server error (`internal_error`). Safe to retry.

---

[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)