Delivery API

Leia páginas, entradas, globais, rotas e redirecionamentos publicados do Atlas e informe o build do seu site.

Esta página foi traduzida do inglês. Se houver qualquer diferença, vale a versão em inglês. Ler em inglês

A Delivery API é a forma como o seu site lê o conteúdo publicado. Chame-a somente a partir de código de servidor.

URL base e autenticação

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

Cada token pertence a um ambiente. Development e Production têm tokens separados.
Os tokens têm 43 caracteres aleatórios, são exibidos uma única vez, valem de 1 a 365 dias e podem ser revogados a qualquer momento no Studio. O Atlas armazena apenas uma impressão digital.
Um token de Production lê somente o release ativo daquele ambiente.

Cache

As respostas publicadas trazem:

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

Envie If-None-Match com o último ETag; o Atlas responde 304 Not Modified quando nada mudou. Combine isso com webhooks para atualizar ao publicar. As respostas de pré-visualização e de deployment são private, no-store.

Endpoints

`GET /site`

O ambiente, o release ativo dele (Production), a versão do conteúdo e o digest e a versão do contrato ativo.

`GET /routes`

Todas as rotas publicadas, para o seu sitemap e para a geração estática: route, pageType, entryId, title, lastModified, noindex, locales. Até 5.000 rotas.

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

Uma página publicada.

Campo	Conteúdo
`page`	`id`, `route`, `title`, `pageType`, `publishedAt`, `entryId`
`document`	`pageType`, `pageFields` e `regions`: cada região é uma lista ordenada de seções
`document.regions[key][n]`	`id`, `component { id, version }`, `props`, `hidden`
`entry`	A entrada vinculada à página, se o tipo de página tiver uma
`seo`	`title`, `description`, `noindex`, `structuredDataType`, `canonicalPath`, `faq`
`head`	`title`, `meta[]`, `links[]` e `jsonLd[]` prontos para imprimir, ou `null` com `headProblem`
`assets`	Todas as imagens que a página usa, por id de asset: `url`, `renditions`, `alt`, `focalPoint`
`locale`, `direction`, `translation`, `alternates`	Idioma da resposta, `ltr`/`rtl`, se faltava uma tradução e os outros locales
`etag`	O ETag da revisão

404 quando nada está publicado naquela rota. Ignore as seções em que hidden é true. Veja Busca e respostas de IA para usar o head.

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

Uma página em rascunho para um link de pré-visualização. Somente em Development (404 em Production). Nunca a coloque em cache. 403 PREVIEW_INVALID para um token inválido, 410 PREVIEW_EXPIRED após 15 minutos.

`GET /entries?collection=projects`

Entradas de uma coleção.

Parâmetro	Exemplo	Observações
`collection`	`projects`	Obrigatório
`locale`	`ar`
`filter`	`category:water,featured:true`	Pares `field:value`, separados por vírgula
`sort`	`-publishedAt`, `title`, `slug`, `featured`, `field.year`	Use o prefixo `-` para ordem decrescente
`fields`	`title,slug,image`	Retorna somente estes campos
`limit`	`20`	Até 100. Sempre defina; sem ele a resposta pode ficar grande
`page`	`2`

Retorna entries, assets e meta.pagination.

`GET /feed?collection=news&limit=20`

As entradas mais recentes de uma coleção editorial, para RSS e listagens de notícias. 404 FEED_NOT_EDITORIAL para as demais coleções.

`GET /globals?locale=en`

Conteúdo compartilhado, como site-header e site-footer: { globals: { key: { data, revision, publishedAt } }, assets }.

`GET /redirects`

{ redirects: [{ from, to, status }] }. Aplique-os no seu middleware ou nos redirects do next.config.

`GET /media/{assetId}?rendition=…`

Redireciona (302) para uma URL de imagem assinada, válida por 15 minutos. Não precisa de token, então você pode usá-la em <img src>.

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

Arquivos para a raiz do seu site, gerados a partir do release no ar (Production) ou bloqueados (Development: sitemap vazio, Disallow: /, X-Robots-Tag: noindex, nofollow). Faça proxy deles a partir do seu próprio domínio para que o token fique no seu servidor; veja Busca e respostas de IA. 409 SITE_ADDRESS_MISSING até que o ambiente tenha um endereço de site.

Informar um deployment

POST /deployments, chamado pelo seu site quando ele inicia:

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

O state da resposta é in-sync, missing-components, different-contract, unknown-contract ou no-contract, com o digest ativo e os componentes ausentes, se houver. runtime é node ou cloudflare-workers. Até 500 componentes.

Erros

Os erros são JSON com um code estável. Veja Limites e erros.

URL base e autenticação

Cache

Endpoints

GET /site

GET /routes

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

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

GET /entries?collection=projects

GET /feed?collection=news&limit=20

GET /globals?locale=en

GET /redirects

GET /media/{assetId}?rendition=…

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