sites

Apply a site plan

A whole site's content in ONE call: business details, theme and navigation (merged onto the draft), entries, pictures (as images:place takes them) and the name. The starter's sample entries are deleted unless the plan keeps them. Validated together: if any part is refused, nothing is written and the 400 lists every part to fix. One history entry, and the build starts. Free: stock pictures cost no credits. Made for a first version and for a large rework.

POST/v1/sites/{site_id}/plan:apply

Request

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>"
}'

import json
import requests

url = "https://api.atelier201.com/v1/sites/<site_id>/plan:apply"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"name\":\"<string>\",\"singletons\":{},\"entries\":[{\"collection\":\"<string>\",\"slug\":\"<string>\"}],\"images\":[{\"target\":\"<string>\",\"alt\":\"<string>\"}],\"keep_samples\":true,\"summary\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.atelier201.com/v1/sites/<site_id>/plan:apply", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "<string>",
    "singletons": {},
    "entries": [
      {
        "collection": "<string>",
        "slug": "<string>"
      }
    ],
    "images": [
      {
        "target": "<string>",
        "alt": "<string>"
      }
    ],
    "keep_samples": true,
    "summary": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.atelier201.com/v1/sites/<site_id>/plan:apply");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"name\":\"<string>\",\"singletons\":{},\"entries\":[{\"collection\":\"<string>\",\"slug\":\"<string>\"}],\"images\":[{\"target\":\"<string>\",\"alt\":\"<string>\"}],\"keep_samples\":true,\"summary\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.atelier201.com/v1/sites/<site_id>/plan:apply", bytes.NewBuffer([]byte("{\"name\":\"<string>\",\"singletons\":{},\"entries\":[{\"collection\":\"<string>\",\"slug\":\"<string>\"}],\"images\":[{\"target\":\"<string>\",\"alt\":\"<string>\"}],\"keep_samples\":true,\"summary\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.atelier201.com/v1/sites/<site_id>/plan:apply"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"name\":\"<string>\",\"singletons\":{},\"entries\":[{\"collection\":\"<string>\",\"slug\":\"<string>\"}],\"images\":[{\"target\":\"<string>\",\"alt\":\"<string>\"}],\"keep_samples\":true,\"summary\":\"<string>\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.atelier201.com/v1/sites/<site_id>/plan:apply")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"name\":\"<string>\",\"singletons\":{},\"entries\":[{\"collection\":\"<string>\",\"slug\":\"<string>\"}],\"images\":[{\"target\":\"<string>\",\"alt\":\"<string>\"}],\"keep_samples\":true,\"summary\":\"<string>\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/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>"
}

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

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

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

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

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

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

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

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

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

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

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

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

Requires sites:write. Costs no credits: stock pictures are free. The path ends in /plan:apply. Changes the draft only. Visitors see nothing until you publish.

The fastest way to write a first version of a site, or to rework one: everything a first version needs, in one request. Read the content model first for the fields.

name: the site’s name in Atelier201.
singletons: business, theme, navigation… Each is merged onto what the draft holds, key by key at the top level; a nested group you give (such as hero or colors) replaces that group.
entries: up to 200 entries to create, update or delete, as Save many entries takes them.
images: up to 12 pictures, as Put a picture in an image field takes them: target, alt, and one of query, stock_id or media_path. A picture that cannot be found comes back with a warning, and the rest of the plan is still applied.
keep_samples: the starter’s sample entries (service-one, service-two) are deleted unless the plan writes them or this is true.

Everything is validated before anything is written. If any part is refused, nothing is saved and the 400 lists every part to fix, so you correct them all in one pass. On success it is one history entry and the build starts: the response carries build. Review the publish afterwards: it refuses while any of the starter’s sample text is left.

Authorizations

Authorizationbearerin headerrequired

Path parameters

site_idstringrequired

The site's id, or its slug (the address before .atelier201.page).

Body

application/jsonrequired

namestringlength: 1–80 chars

The site's name in Atelier201 (the business name).

singletonsRecord<string, Record<string, object>>

business, theme, navigation...: each merged onto what the draft holds (top-level keys; a nested group given here replaces that group). Fields as get_content_model defines them.

entriesobject[]items: 1–200 items

Entries to create, update or delete (delete: true), as save_entries takes them, up to 200.

Show child attributes

entries.collectionstringrequired

entries.slugstringrequired

Lowercase letters, digits and hyphens.

entries.dataRecord<string, object>

The fields, as the collection's schema defines them (not for delete).

entries.bodystringlength: ≤ 500000 chars

Markdown body, for content collections.

entries.deleteboolean

true to delete this entry.

imagesobject[]items: ≤ 12 items

Pictures to put in image fields, as place_image takes them (target, alt, and one of query, stock_id, media_path). A picture that cannot be found is a warning; the rest is still applied.

Show child attributes

images.targetstringrequiredlength: 3–200 chars

The image field: business:/hero/image for business details, or /:/image for an entry (services/sourdough:/image). get_content_model shows the image fields.

images.altstringrequiredlength: 1–300 chars

What the picture shows, for people who cannot see it, in the site's language. Saved in the alt field next to the image when there is one.

images.querystringlength: ≤ 100 chars

A description searched in the free stock library, in English with concrete words ("minimalist concrete house at dusk"): the first result is imported.

images.stock_idstringlength: ≤ 20 chars

A result id from search_stock_media, when you chose the picture yourself.

images.media_pathstringlength: ≤ 200 chars

A file already in the site's media (/media/storefront.jpg), e.g. the owner's own photo.

images.orientationenum<string>one of: landscape, portrait, square

With query: the shape to search for. Landscape suits a hero.

keep_samplesboolean

Keep the starter's sample entries (service-one, service-two). Default: they are deleted unless the plan writes them.

summarystringlength: ≤ 200 chars

One sentence for the history.

Response

application/json

Apply a site plan

dataRecord<string, object>required

Show child attributes

data.renamedstringnullrequired

data.singletonsstring[]required

The singletons written.

data.savedintegerrequiredrange: -9007199254740991–9007199254740991

data.deletedintegerrequiredrange: -9007199254740991–9007199254740991

data.imagesobject[]required

Show child attributes

data.images.targetstringrequired

data.images.imagestringnullrequired

data.images.creditstringnullrequired

data.images.warningstringnullrequired

data.revisionstring | nullrequired

data.changedbooleanrequired

data.buildobject | nullrequired

The build this change started (or joined): the preview follows it. No build_site call needed.

Show child attributes

data.build.idstringrequired

data.build.statestringrequired

data.build.next_actionstringrequired

data.next_actionstringrequired

request_idstringrequired

Apply a site plan

Authorizations

Path parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown

Cookies