---
title: "Aplicar um plano ao site"
description: "Grave os dados comerciais, o tema, a navegação, as entradas e as imagens de um site em uma única chamada, como uma única entrada no histórico."
canonical: "https://atelier201.com/docs/pt/api/sites/apply-plan"
updated: "2026-11-06"
---

# Aplicar um plano ao site

Requer `sites:write`. Não consome créditos: as imagens de banco são gratuitas. O caminho termina em `/plan:apply`. Altera apenas o rascunho. Os visitantes não veem nada até você [publicar](/docs/api/publishing/publish).

A maneira mais rápida de criar a primeira versão de um site ou reformular um que já existe: tudo o que uma primeira versão precisa, em uma única solicitação. Consulte primeiro o [modelo de conteúdo](/docs/api/content/model) para conhecer os campos.

- **`name`**: o nome do site no Atelier201.
- **`singletons`**: `business`, `theme`, `navigation`... Cada item é mesclado ao conteúdo atual do rascunho, chave por chave no nível superior; um grupo aninhado que você fornecer (como `hero` ou `colors`) substitui o grupo inteiro.
- **`entries`**: até 200 entradas para criar, atualizar ou excluir, no formato aceito por [Salvar várias entradas](/docs/api/content/save-entries).
- **`images`**: até 12 imagens, no formato aceito por [Inserir uma imagem em um campo de imagem](/docs/api/media/place): `target`, `alt` e um dos campos `query`, `stock_id` ou `media_path`. Se não for possível encontrar uma imagem, a resposta inclui `warning`, e o restante do plano ainda é aplicado.
- **`keep_samples`**: as entradas de exemplo do Starter (`service-one`, `service-two`) são excluídas, a menos que o plano as grave ou que o valor seja `true`.

Tudo é validado antes de qualquer gravação. Se alguma parte for recusada, nada será salvo e o `400` listará tudo o que precisa ser corrigido, para que você resolva tudo de uma só vez. Se a operação for bem-sucedida, será criada uma única entrada no histórico e a compilação começará: a resposta incluirá `build`. Depois, [revise a publicação](/docs/api/publishing/review): ela será recusada enquanto ainda houver qualquer texto de exemplo do 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): O id do site ou seu slug (o endereço antes de .atelier201.page).

## Body

`application/json`, required

- `name` (`string`, length: `1–80 chars`): O nome do site no Atelier201 (o nome da empresa).
- `singletons` (`Record<string, Record<string, object>>`): business, theme, navigation...: cada grupo é mesclado ao conteúdo atual do rascunho (chaves de nível superior; um grupo aninhado informado aqui substitui esse grupo). Os campos seguem a definição de get_content_model.
- `entries` (`object[]`, items: `1–200 items`): Entradas a criar, atualizar ou excluir (delete: true), no formato aceito por save_entries, até 200.
- `entries.collection` (`string`, required)
- `entries.slug` (`string`, required): Letras minúsculas, dígitos e hífens.
- `entries.data` (`Record<string, object>`): Os campos, conforme definidos pelo esquema da coleção (não se aplica à exclusão).
- `entries.body` (`string`, length: `≤ 500000 chars`): Corpo em Markdown, para coleções de conteúdo.
- `entries.delete` (`boolean`): true para excluir esta entrada.
- `images` (`object[]`, items: `≤ 12 items`): Imagens a inserir em campos de imagem, no formato aceito por place_image (target, alt e um entre query, stock_id e media_path). Se uma imagem não for encontrada, será emitido um aviso; as demais alterações ainda serão aplicadas.
- `images.target` (`string`, required, length: `3–200 chars`): O campo de imagem: business:/hero/image para os dados da empresa ou <collection>/<slug>:/image para um registro (services/sourdough:/image). get_content_model mostra os campos de imagem.
- `images.alt` (`string`, required, length: `1–300 chars`): O que a imagem mostra, para pessoas que não conseguem vê-la, no idioma do site. O texto é salvo no campo alt ao lado da imagem, quando disponível.
- `images.query` (`string`, length: `≤ 100 chars`): Uma descrição para buscar na biblioteca de imagens gratuitas, em inglês e com termos concretos ("minimalist concrete house at dusk"): o primeiro resultado é importado.
- `images.stock_id` (`string`, length: `≤ 20 chars`): O ID de um resultado de search_stock_media, quando você escolheu a imagem.
- `images.media_path` (`string`, length: `≤ 200 chars`): Um arquivo que já está na mídia do site (/media/storefront.jpg), por exemplo, uma foto do proprietário.
- `images.orientation` (`enum<string>`, one of: `landscape, portrait, square`): Com query: o formato da imagem a buscar. Landscape é adequado para uma imagem de destaque.
- `keep_samples` (`boolean`): Manter os registros de exemplo do starter (service-one, service-two). Por padrão, eles são excluídos, a menos que o plano os crie.
- `summary` (`string`, length: `≤ 200 chars`): Uma frase para o histórico.

## Response

**200**: Aplicar um plano ao site

- `data` (`Record<string, object>`, required)
- `data.renamed` (`string,null`, required)
- `data.singletons` (`string[]`, required): Os singletons gravados.
- `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): A compilação iniciada (ou associada) por esta alteração: a prévia acompanha essa compilação. Não é necessário chamar 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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>"
}'
```