Delivery API

Veröffentlichte Seiten, Einträge, Globals, Routen und Weiterleitungen aus Atlas lesen und den Build Ihrer Website melden.

Diese Seite wurde aus dem Englischen übersetzt. Bei Abweichungen gilt die englische Version. Auf Englisch lesen

Die Delivery API ist der Weg, auf dem Ihre Website veröffentlichte Inhalte liest. Rufen Sie sie ausschließlich aus Servercode auf.

Basis-URL und Authentifizierung

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

Jedes Token gehört zu einer Umgebung. Development und Production haben getrennte Tokens.
Tokens bestehen aus 43 zufälligen Zeichen, werden einmalig angezeigt, sind 1 bis 365 Tage gültig und können jederzeit in Studio widerrufen werden. Atlas speichert nur einen Fingerabdruck.
Ein Production-Token liest nur das aktive Release dieser Umgebung.

Caching

Veröffentlichte Antworten enthalten:

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

Senden Sie If-None-Match mit dem letzten ETag; Atlas antwortet mit 304 Not Modified, wenn sich nichts geändert hat. Kombinieren Sie das mit Webhooks, um bei der Veröffentlichung zu aktualisieren. Antworten für Vorschau und Deployments sind private, no-store.

Endpunkte

`GET /site`

Die Umgebung, ihr aktives Release (Production), die Inhaltsversion sowie Digest und Version des aktiven Contracts.

`GET /routes`

Jede veröffentlichte Route, für Ihre Sitemap und statische Generierung: route, pageType, entryId, title, lastModified, noindex, locales. Bis zu 5.000 Routen.

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

Eine veröffentlichte Seite.

Feld	Inhalt
`page`	`id`, `route`, `title`, `pageType`, `publishedAt`, `entryId`
`document`	`pageType`, `pageFields` und `regions`: Jede Region ist eine geordnete Liste von Abschnitten
`document.regions[key][n]`	`id`, `component { id, version }`, `props`, `hidden`
`entry`	Der an die Seite gebundene Eintrag, falls ihr Seitentyp einen hat
`seo`	`title`, `description`, `noindex`, `structuredDataType`, `canonicalPath`, `faq`
`head`	Druckfertige `title`, `meta[]`, `links[]` und `jsonLd[]`, oder `null` mit `headProblem`
`assets`	Jedes von der Seite genutzte Bild, nach Asset-ID: `url`, `renditions`, `alt`, `focalPoint`
`locale`, `direction`, `translation`, `alternates`	Sprache der Antwort, `ltr`/`rtl`, ob eine Übersetzung fehlte, und weitere Locales
`etag`	Der ETag der Revision

404, wenn an dieser Route nichts veröffentlicht ist. Überspringen Sie Abschnitte, bei denen hidden wahr ist. Zur Verwendung von head siehe Suche und KI-Antworten.

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

Eine Entwurfs-Seite für einen Vorschau-Link. Nur Development (404 in Production). Cachen Sie sie nie. 403 PREVIEW_INVALID bei ungültigem Token, 410 PREVIEW_EXPIRED nach 15 Minuten.

`GET /entries?collection=projects`

Einträge einer Collection.

Parameter	Beispiel	Hinweise
`collection`	`projects`	Pflicht
`locale`	`ar`
`filter`	`category:water,featured:true`	`field:value`-Paare, durch Kommas getrennt
`sort`	`-publishedAt`, `title`, `slug`, `featured`, `field.year`	Mit vorangestelltem `-` absteigend
`fields`	`title,slug,image`	Nur diese Felder zurückgeben
`limit`	`20`	Bis zu 100. Setzen Sie ihn immer; ohne ihn kann die Antwort groß werden
`page`	`2`

Liefert entries, assets und meta.pagination.

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

Die neuesten Einträge einer redaktionellen Collection, für RSS und News-Listen. 404 FEED_NOT_EDITORIAL für andere Collections.

`GET /globals?locale=en`

Geteilte Inhalte wie site-header und site-footer: { globals: { key: { data, revision, publishedAt } }, assets }.

`GET /redirects`

{ redirects: [{ from, to, status }] }. Wenden Sie sie in Ihrer Middleware oder den Redirects in next.config an.

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

Leitet (302) auf eine signierte Bild-URL weiter, die 15 Minuten gültig ist. Kein Token nötig, sodass Sie sie in <img src> verwenden können.

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

Dateien für das Stammverzeichnis Ihrer Site, erstellt aus dem aktiven Release (Production) oder gesperrt (Development: leere Sitemap, Disallow: /, X-Robots-Tag: noindex, nofollow). Leiten Sie sie über Ihre eigene Domain weiter, damit das Token auf Ihrem Server bleibt; siehe Suche und KI-Antworten. 409 SITE_ADDRESS_MISSING, bis die Umgebung eine Website-Adresse hat.

Ein Deployment melden

POST /deployments, von Ihrer Website beim Start aufgerufen:

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

Der state der Antwort ist in-sync, missing-components, different-contract, unknown-contract oder no-contract, mit dem aktiven Digest und gegebenenfalls fehlenden Komponenten. runtime ist node oder cloudflare-workers. Bis zu 500 Komponenten.

Fehler

Fehler sind JSON mit einem stabilen code. Siehe Limits und Fehler.

Basis-URL und Authentifizierung

Caching

Endpunkte

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