# One turn of designing the site by conversation

`POST /hosting/sites/{id}/design/turn` · Rivier · hosting

One turn of designing the site by conversation: describe it, answer the (at most two) questions, refine the plan, approve it to build the pages, then refine at site, page or block scope. Changes go through the patch API, so locks, undo and approval of changes to live pages hold.

- Scope: hosting:write
- Mcp: rivier_site_design_turn
- Graphql: Mutation.hostingDesignTurn
- Sdk: hosting.design.turn
- Cli: hosting design turn

## Parameters

- `id` (path, required), string

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 4000
    },
    "answers": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 1000
      }
    },
    "scope": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "site"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "page"
            },
            "pageId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "kind",
            "pageId"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "block"
            },
            "pageId": {
              "type": "string",
              "format": "uuid"
            },
            "blockId": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "pageId",
            "blockId"
          ],
          "additionalProperties": false
        }
      ]
    },
    "approvePlan": {
      "type": "boolean"
    },
    "turnId": {
      "type": "string",
      "maxLength": 80
    },
    "dryRun": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

## Responses

- `200`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/hosting/sites/{id}/design/turn' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "string",
  "answers": {},
  "scope": {
    "kind": "site"
  },
  "approvePlan": false,
  "turnId": "string",
  "dryRun": false
}'
```