API Delivery

Lisez les pages, entrées, éléments globaux, routes et redirections publiés d'Atlas, et signalez le build de votre site web.

Cette page a été traduite de l'anglais. En cas de divergence, la version anglaise fait foi. Lire en anglais

L’API Delivery est le moyen par lequel votre site web lit le contenu publié. Appelez-la uniquement depuis du code serveur.

URL de base et authentification

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

Chaque jeton appartient à un seul environnement. Development et Production ont des jetons distincts.
Les jetons comptent 43 caractères aléatoires, ne sont affichés qu’une fois, sont valables de 1 à 365 jours et peuvent être révoqués à tout moment dans Studio. Atlas n’en conserve qu’une empreinte.
Un jeton Production ne lit que la release live de cet environnement.

Mise en cache

Les réponses publiées comportent :

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

Envoyez If-None-Match avec le dernier ETag ; Atlas répond 304 Not Modified lorsque rien n’a changé. Combinez cela avec les webhooks pour rafraîchir à la publication. Les réponses d’aperçu et de déploiement sont private, no-store.

Points d’accès

`GET /site`

L’environnement, sa release live (Production), la version du contenu ainsi que l’empreinte et la version du contrat actif.

`GET /routes`

Chaque route publiée, pour votre sitemap et la génération statique : route, pageType, entryId, title, lastModified, noindex, locales. Jusqu’à 5 000 routes.

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

Une page publiée.

Champ	Contenu
`page`	`id`, `route`, `title`, `pageType`, `publishedAt`, `entryId`
`document`	`pageType`, `pageFields`, et `regions` : chaque région est une liste ordonnée de sections
`document.regions[key][n]`	`id`, `component { id, version }`, `props`, `hidden`
`entry`	L’entrée liée à la page, si son type de page en possède une
`seo`	`title`, `description`, `noindex`, `structuredDataType`, `canonicalPath`, `faq`
`head`	`title`, `meta[]`, `links[]` et `jsonLd[]` prêts à être affichés, ou `null` avec `headProblem`
`assets`	Chaque image utilisée par la page, par identifiant d’asset : `url`, `renditions`, `alt`, `focalPoint`
`locale`, `direction`, `translation`, `alternates`	Langue de la réponse, `ltr`/`rtl`, indication qu’une traduction manquait, et autres locales
`etag`	L’ETag de la révision

404 lorsque rien n’est publié à cette route. Ignorez les sections dont hidden vaut true. Voir Recherche et réponses IA pour utiliser head.

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

Une page brouillon pour un lien d’aperçu. Development uniquement (404 en Production). Ne la mettez jamais en cache. 403 PREVIEW_INVALID pour un jeton incorrect, 410 PREVIEW_EXPIRED après 15 minutes.

`GET /entries?collection=projects`

Les entrées d’une collection.

Paramètre	Exemple	Remarques
`collection`	`projects`	Obligatoire
`locale`	`ar`
`filter`	`category:water,featured:true`	Paires `field:value`, séparées par des virgules
`sort`	`-publishedAt`, `title`, `slug`, `featured`, `field.year`	Préfixe `-` pour un ordre décroissant
`fields`	`title,slug,image`	Ne renvoie que ces champs
`limit`	`20`	Jusqu’à 100. Définissez-le toujours ; sans lui, la réponse peut être volumineuse
`page`	`2`

Renvoie entries, assets et meta.pagination.

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

Les dernières entrées d’une collection éditoriale, pour RSS et les listes d’actualités. 404 FEED_NOT_EDITORIAL pour les autres collections.

`GET /globals?locale=en`

Le contenu partagé tel que site-header et site-footer : { globals: { key: { data, revision, publishedAt } }, assets }.

`GET /redirects`

{ redirects: [{ from, to, status }] }. Appliquez-les dans votre middleware ou dans les redirections de next.config.

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

Redirige (302) vers une URL d’image signée valable 15 minutes. Aucun jeton n’est nécessaire, vous pouvez donc l’utiliser dans <img src>.

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

Fichiers pour la racine de votre site, construits à partir de la release live (Production) ou verrouillés (Development : sitemap vide, Disallow: /, X-Robots-Tag: noindex, nofollow). Relayez-les depuis votre propre domaine afin que le jeton reste sur votre serveur ; voir Recherche et réponses IA. 409 SITE_ADDRESS_MISSING tant que l’environnement n’a pas d’adresse de site web.

Signaler un déploiement

POST /deployments, appelé par votre site web lorsqu’il démarre :

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

Le state de la réponse vaut in-sync, missing-components, different-contract, unknown-contract ou no-contract, avec l’empreinte active et les éventuels composants manquants. runtime vaut node ou cloudflare-workers. Jusqu’à 500 composants.

Erreurs

Les erreurs sont du JSON avec un code stable. Voir Limites et erreurs.

URL de base et authentification

Mise en cache

Points d’accès

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