Delivery API

Delivery API — это способ, которым ваш сайт читает опубликованный контент. Вызывайте его только из серверного кода.

Базовый URL и аутентификация

https://<delivery host>/v1/delivery/environments/{environmentId}
Authorization: PublishedConsumer <delivery token>

• Каждый токен принадлежит одному окружению. У Development и Production разные токены.
• Токены состоят из 43 случайных символов, показываются один раз, действуют от 1 до 365 дней и могут быть отозваны в любой момент в Studio. Atlas хранит только отпечаток.
• Токен Production читает только действующий релиз этого окружения.

Кеширование

Опубликованные ответы содержат:

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300
ETag: W/"…"
X-Atlas-Content-Version: …
Vary: Authorization, Accept-Encoding

Отправляйте If-None-Match с последним ETag; если ничего не изменилось, Atlas отвечает 304 Not Modified. Сочетайте это с вебхуками, чтобы обновляться при публикации. Ответы предпросмотра и развёртывания имеют private, no-store.

Конечные точки

GET /site

Окружение, его действующий релиз (Production), версия контента, а также дайджест и версия активного контракта.

GET /routes

Каждый опубликованный маршрут — для вашей карты сайта и статической генерации: route, pageType, entryId, title, lastModified, noindex, locales. До 5 000 маршрутов.

GET /pages?route=/about&locale=en

Одна опубликованная страница.

Поле	Содержимое
page	id, route, title, pageType, publishedAt, entryId
document	pageType, pageFields и regions: каждая область — упорядоченный список секций
document.regions[key][n]	id, component { id, version }, props, hidden
entry	Связанная со страницей запись, если у её типа страницы она есть
seo	title, description, noindex, structuredDataType, canonicalPath, faq
head	Готовые к выводу title, meta[], links[] и jsonLd[] либо null с headProblem
assets	Каждое изображение, которое использует страница, по идентификатору ресурса: url, renditions, alt, focalPoint
locale, direction, translation, alternates	Язык ответа, ltr/rtl, отсутствовал ли перевод, и другие языки
etag	ETag ревизии

404, если по этому маршруту ничего не опубликовано. Пропускайте секции, у которых hidden равно true. О том, как использовать head, см. Поиск и ответы ИИ.

GET /preview/pages?token=…&locale=en

Черновик страницы для ссылки предпросмотра. Только Development (404 в Production). Никогда не кешируйте его. 403 PREVIEW_INVALID при неверном токене, 410 PREVIEW_EXPIRED через 15 минут.

GET /entries?collection=projects

Записи коллекции.

Параметр	Пример	Примечания
collection	projects	Обязателен
locale	ar
filter	category:water,featured:true	Пары field:value через запятую
sort	-publishedAt, title, slug, featured, field.year	Префикс - для убывания
fields	title,slug,image	Возвращать только эти поля
limit	20	До 100. Всегда задавайте его; без него ответ может быть большим
page	2

Возвращает entries, assets и meta.pagination.

GET /feed?collection=news&limit=20

Последние записи редакционной коллекции — для RSS и списков новостей. Для других коллекций 404 FEED_NOT_EDITORIAL.

GET /globals?locale=en

Общий контент, например site-header и site-footer: { globals: { key: { data, revision, publishedAt } }, assets }.

GET /redirects

{ redirects: [{ from, to, status }] }. Применяйте их в своём middleware или в редиректах next.config.

GET /media/{assetId}?rendition=…

Перенаправляет (302) на подписанный URL изображения, действительный 15 минут. Токен не нужен, поэтому его можно использовать в <img src>.

GET /sitemap.xml, GET /robots.txt, GET /llms.txt

Файлы для корня вашего сайта, построенные по действующему релизу (Production) или ограниченные (Development: пустая карта сайта, Disallow: /, X-Robots-Tag: noindex, nofollow). Проксируйте их со своего домена, чтобы токен оставался на вашем сервере; см. Поиск и ответы ИИ. 409 SITE_ADDRESS_MISSING, пока у окружения нет адреса сайта.

Сообщение о развёртывании

POST /deployments, вызывается вашим сайтом при запуске:

{
  "bundleDigest": "<sha256 hex of the contract bundle this build renders>",
  "bundleVersion": "1.4.0",
  "commit": "a1b2c3d",
  "components": [{ "id": "acme.home.hero", "version": "1.0.0" }],
  "runtime": "node",
  "siteOrigin": "https://dev.example.com"
}

Поле state в ответе принимает значения in-sync, missing-components, different-contract, unknown-contract или no-contract и сопровождается активным дайджестом и всеми отсутствующими компонентами. runtime — node или cloudflare-workers. До 500 компонентов.

Ошибки

Ошибки — это JSON со стабильным полем code. См. Лимиты и ошибки.