sites

Put a picture in an image field

Puts a picture in an image field of business details or an entry, with its alt text, in ONE history entry, and starts the build. The picture is a file of the site's media (media_path), a stock result you chose (stock_id), or a description searched in the free stock library (query, first result imported with its credit). Free: stock pictures cost no credits.

POST/v1/sites/{site_id}/images:place

Request

curl --request POST \
  --url 'https://api.atelier201.com/v1/sites/<site_id>/images:place' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": "<string>",
  "alt": "<string>"
}'

import json
import requests

url = "https://api.atelier201.com/v1/sites/<site_id>/images:place"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"target\":\"<string>\",\"alt\":\"<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>/images:place", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "target": "<string>",
    "alt": "<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>/images:place");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"target\":\"<string>\",\"alt\":\"<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>/images:place", bytes.NewBuffer([]byte("{\"target\":\"<string>\",\"alt\":\"<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>/images:place"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"target\":\"<string>\",\"alt\":\"<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>/images:place")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"target\":\"<string>\",\"alt\":\"<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": {
    "target": "<string>",
    "image": "<string>",
    "alt": "<string>",
    "alt_field": null,
    "credit": 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. The path ends in /images:place. Changes the draft only. Visitors see nothing until you publish.

One call for “put a photo here”. target is the image field: business:/hero/image for the home page picture, or <collection>/<slug>:/image for an entry, such as services/sourdough:/image. The content model lists the image fields.

Give exactly one source:

query: a description, in English with concrete words. The free stock library is searched and the first result is imported with its credit. orientation narrows the shape.
stock_id: a result you chose with Search stock media.
media_path: a file already in the site’s media, such as the owner’s own photo.

alt is saved in the alt field next to the image when the content has one (imageAlt, for example), and with the media file. The change is one history entry, and the build starts: the response carries build. A search that finds nothing is a 404, and nothing is written.

Authorizations

Authorizationbearerin headerrequired

Path parameters

site_idstringrequired

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

Body

application/jsonrequired

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.

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.

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.

stock_idstringlength: ≤ 20 chars

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

media_pathstringlength: ≤ 200 chars

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

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

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

Response

application/json

Put a picture in an image field

dataRecord<string, object>required

Show child attributes

data.targetstringrequired

data.imagestringrequired

The /media path now in the field.

data.altstringrequired

data.alt_fieldstringnullrequired

Where the alt text was saved, or null when the content has no alt field.

data.creditstringnullrequired

data.revisionstringrequiredlength: 40–40 chars

A Git commit id (40 hex characters) of the site's repository.

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

curl --request POST \ --url 'https://api.atelier201.com/v1/sites/<site_id>/images:place' \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "target": "<string>", "alt": "<string>" }'

{ "data": { "target": "<string>", "image": "<string>", "alt": "<string>", "alt_field": null, "credit": 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>" }

Put a picture in an image field

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