---
title: "Applicare un piano al sito"
description: "Scrivi in un'unica chiamata i dati aziendali, il tema, la navigazione, i contenuti e le immagini di un sito, creando una sola voce nella cronologia."
canonical: "https://atelier201.com/docs/it/api/sites/apply-plan"
updated: "2026-11-06"
---

# Applicare un piano al sito

Richiede `sites:write`. Non costa crediti: le immagini stock sono gratuite. Il percorso termina con `/plan:apply`. Le modifiche riguardano solo la bozza. I visitatori non vedranno nulla finché non [pubblichi](/docs/api/publishing/publish).

Il modo più rapido per creare la prima versione di un sito o rielaborarne uno: tutto ciò che serve per una prima versione, in un'unica richiesta. Per conoscere i campi, leggi prima il [modello dei contenuti](/docs/api/content/model).

- **`name`**: il nome del sito in Atelier201.
- **`singletons`**: `business`, `theme`, `navigation`... Ogni elemento viene unito a ciò che è presente nella bozza, chiave per chiave al livello principale; un gruppo annidato fornito (come `hero` o `colors`) sostituisce il gruppo corrispondente.
- **`entries`**: fino a 200 elementi da creare, aggiornare o eliminare, nel formato previsto da [Salvare più elementi](/docs/api/content/save-entries).
- **`images`**: fino a 12 immagini, nel formato previsto da [Inserire un'immagine in un campo immagine](/docs/api/media/place): `target`, `alt` e uno tra `query`, `stock_id` o `media_path`. Se un'immagine non viene trovata, la risposta include un `warning` e il resto del piano viene comunque applicato.
- **`keep_samples`**: gli elementi di esempio dello starter (`service-one`, `service-two`) vengono eliminati, a meno che il piano non li crei o che questo valore sia `true`.

Tutto viene convalidato prima di salvare qualsiasi modifica. Se una parte viene rifiutata, non viene salvato nulla e la risposta `400` elenca tutte le parti da correggere, così puoi sistemarle in un solo passaggio. Se l'operazione riesce, viene creata una sola voce nella cronologia e si avvia la compilazione: la risposta include `build`. In seguito, [verifica la pubblicazione](/docs/api/publishing/review): l'operazione viene rifiutata se è rimasto del testo di esempio dello starter.

```http
POST https://api.atelier201.com/v1/sites/{site_id}/plan:apply
```

## Authorizations

- `Authorization` (bearer, in header, required)

## Path parameters

- `site_id` (`string`, required): L'ID del sito o il suo slug (l'indirizzo prima di .atelier201.page).

## Body

`application/json`, required

- `name` (`string`, length: `1–80 chars`): Il nome del sito in Atelier201 (il nome dell'attività).
- `singletons` (`Record<string, Record<string, object>>`): business, theme, navigation...: ciascun elemento viene integrato nei dati presenti nella bozza (chiavi di primo livello; un gruppo nidificato fornito qui sostituisce quel gruppo). I campi sono quelli definiti da get_content_model.
- `entries` (`object[]`, items: `1–200 items`): Voci da creare, aggiornare o eliminare (delete: true), nel formato accettato da save_entries, fino a 200.
- `entries.collection` (`string`, required)
- `entries.slug` (`string`, required): Lettere minuscole, cifre e trattini.
- `entries.data` (`Record<string, object>`): I campi, come definiti dallo schema della raccolta (non per l'eliminazione).
- `entries.body` (`string`, length: `≤ 500000 chars`): Corpo in Markdown, per le raccolte di contenuti.
- `entries.delete` (`boolean`): true per eliminare questa voce.
- `images` (`object[]`, items: `≤ 12 items`): Immagini da inserire nei campi immagine, nel formato richiesto da place_image (target, alt e uno tra query, stock_id e media_path). Se un'immagine non viene trovata, viene segnalato un avviso; il resto viene comunque applicato.
- `images.target` (`string`, required, length: `3–200 chars`): Il campo immagine: business:/hero/image per i dettagli dell'attività oppure <collection>/<slug>:/image per una voce (services/sourdough:/image). get_content_model mostra i campi immagine.
- `images.alt` (`string`, required, length: `1–300 chars`): Descrizione di ciò che mostra l'immagine, per chi non può vederla, nella lingua del sito. Se presente, viene salvata nel campo alt accanto all'immagine.
- `images.query` (`string`, length: `≤ 100 chars`): Descrizione da cercare nella libreria di immagini stock gratuite, in inglese e con termini concreti ("minimalist concrete house at dusk"): viene importato il primo risultato.
- `images.stock_id` (`string`, length: `≤ 20 chars`): ID di un risultato di search_stock_media, se hai scelto personalmente l'immagine.
- `images.media_path` (`string`, length: `≤ 200 chars`): File già presente nei contenuti multimediali del sito (/media/storefront.jpg), ad esempio una foto del proprietario.
- `images.orientation` (`enum<string>`, one of: `landscape, portrait, square`): Con query: il formato da cercare. Per un hero è adatto Landscape.
- `keep_samples` (`boolean`): Mantieni le voci di esempio dello starter (service-one, service-two). Per impostazione predefinita, vengono eliminate se il piano non le crea.
- `summary` (`string`, length: `≤ 200 chars`): Una frase per la cronologia.

## Response

**200**: Applica un piano al sito

- `data` (`Record<string, object>`, required)
- `data.renamed` (`string,null`, required)
- `data.singletons` (`string[]`, required): I singleton scritti.
- `data.saved` (`integer`, required, range: `-9007199254740991–9007199254740991`)
- `data.deleted` (`integer`, required, range: `-9007199254740991–9007199254740991`)
- `data.images` (`object[]`, required)
- `data.images.target` (`string`, required)
- `data.images.image` (`string,null`, required)
- `data.images.credit` (`string,null`, required)
- `data.images.warning` (`string,null`, required)
- `data.revision` (`string | null`, required)
- `data.changed` (`boolean`, required)
- `data.build` (`object | null`, required): La build avviata (o a cui si è unita) questa modifica: l'anteprima la segue. Non serve chiamare build_site.
- `data.build.id` (`string`, required)
- `data.build.state` (`string`, required)
- `data.build.next_action` (`string`, required)
- `data.next_action` (`string`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "renamed": null,
    "singletons": [
      "<string>"
    ],
    "saved": 123,
    "deleted": 123,
    "images": [
      {
        "target": "<string>",
        "image": null,
        "credit": null,
        "warning": null
      }
    ],
    "revision": "<string>",
    "changed": true,
    "build": {
      "id": "<string>",
      "state": "<string>",
      "next_action": "<string>"
    },
    "next_action": "<string>"
  },
  "request_id": "<string>"
}
```

**400**: Codici possibili: invalid_request, unknown_field, invalid_parameter, invalid_cursor

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**401**: Codici possibili: authentication_required, invalid_api_key, api_key_expired, api_key_revoked

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**402**: Codici possibili: insufficient_credits

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**403**: Codici possibili: insufficient_scope, feature_not_available, admin_required

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**404**: Codici possibili: resource_not_found

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**409**: Codici possibili: conflict, result_not_ready, idempotency_key_reused

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**410**: Codici possibili: result_expired

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**413**: Codici possibili: request_too_large

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**422**: Codici possibili: request_too_large_for_plan

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**429**: Codici possibili: rate_limited

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**500**: Codici possibili: internal_error

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**503**: Codici possibili: service_unavailable

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**Example request**

```bash
curl --request POST \
  --url 'https://api.atelier201.com/v1/sites/<site_id>/plan:apply' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "singletons": {},
  "entries": [
    {
      "collection": "<string>",
      "slug": "<string>"
    }
  ],
  "images": [
    {
      "target": "<string>",
      "alt": "<string>"
    }
  ],
  "keep_samples": true,
  "summary": "<string>"
}'
```