Skip to Content
ReferenzHeadless-Delivery-API

Headless-Delivery-API

Dies ist eine Entwicklerreferenz. Wenn Sie zum ersten Mal einen Headless-Space einrichten, beginnen Sie mit Einen Headless-Space erstellen.

Jeder Headless-Space stellt seine veröffentlichten Beiträge über eine öffentliche, CDN-cachefähige Lese-API bereit. Es ist keine Authentifizierung und kein API-Schlüssel erforderlich — die API gibt ausschließlich veröffentlichte Beiträge zurück (Entwürfe und geplante Beiträge erscheinen nie), und ein Blog ist per Definition öffentlich.

Die Basis-URL Ihres Space — einschließlich Workspace- und Website-Kennung — wird auf der Seite Delivery API der Website im Kundenportal angezeigt, zusammen mit fertigen Feed-URLs je Sprache. Alle nachfolgenden Pfade sind relativ zu dieser Basis.

Endpunkte

RouteGibt zurück
GET /postsVeröffentlichte Beiträge, neueste zuerst (nur Zusammenfassungsfelder)
GET /posts/{slug}Ein veröffentlichter Beitrag, vollständiger Vertrag (siehe unten)
GET /termsKategorien und Tags mit Beitragsanzahl

Query-Parameter (/posts)

ParameterBeschreibung
languageBeiträge in einer Sprache (z. B. de). Jede Sprache ist ein separater Blog — eine Kampagne pro Sprache.
categoryFiltern nach Kategorie-slug. Schließt sich gegenseitig mit tag aus.
tagFiltern nach Tag-slug. Schließt sich gegenseitig mit category aus.
cursorNächste (ältere) Seite — die nextCursor der vorherigen Antwort übergeben.
beforeVorherige (neuere) Seite — die prevCursor der Antwort übergeben.
limitEinträge pro Seite; Standard und Maximum 50.

language lässt sich mit category oder tag kombinieren: /posts?language=de&category=news ist das „News”-Archiv des deutschen Blogs. /terms?language=de grenzt die Taxonomie auf dieselbe Weise ein.

Paginierung

Listenantworten sind bidirektional: Jede gibt nextCursor (zu älteren Beiträgen) und prevCursor (zu neueren) zurück. Ein null-Cursor bedeutet, dass es in dieser Richtung keine weiteren Seiten gibt — jede Seite wird ausschließlich anhand ihres URL-Tokens gerendert, ohne dass ein Cursor-Verlauf benötigt wird.

Anfragebeispiele und Antwortschemas

Setzen Sie BASE auf die öffentliche Lese-URL Ihrer Website bis einschließlich der Website-ID. Die OpenAPI-Antwortschemas beschreiben die Feldtypen aller drei Endpunkte und welche Felder null sein können.

Blogübersicht

Übergeben Sie die zurückgegebenen Cursor als Zeichenketten. Die Anfragen zeigen die erste Seite und beide Blätterrichtungen. Zeigen Sie einen Link nur bei vorhandenem Cursor.

curl "$BASE/posts?language=en&limit=1"
{ "posts": [ { "id": "post_42", "slug": "studio-notes", "title": "Studio notes", "excerpt": "A look inside our studio.", "categories": [ "News" ], "tags": [ "Design" ], "featuredImage": null, "publishedAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z" } ], "nextCursor": "1782907200000", "prevCursor": null }
feed="$BASE/posts?language=en&limit=1" if next=$(curl -fsS "$feed" | jq -er '.nextCursor // empty'); then older=$(curl -fsS "$feed&cursor=$next") if prev=$(jq -er '.prevCursor // empty' <<< "$older"); then curl "$feed&before=$prev" fi fi

Einzelbeitrag

curl "$BASE/posts/studio-notes"
{ "post": { "id": "post_42", "slug": "studio-notes", "title": "Studio notes", "excerpt": "A look inside our studio.", "categories": [ "News" ], "tags": [ "Design" ], "featuredImage": null, "publishedAt": "2026-07-01T12:00:00.000Z", "updatedAt": "2026-07-01T12:00:00.000Z", "html": "<p>A look inside our studio.</p>", "blocks": [ { "type": "core/paragraph", "content": "A look inside our studio." } ], "bodyImage": null, "metaTitle": null, "metaDescription": null, "keyphrase": null, "author": null, "og": { "title": "Studio notes", "description": "A look inside our studio.", "image": null }, "schema": [ { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Studio notes", "description": "A look inside our studio.", "@id": "https://example.com/blog/studio-notes#article", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://example.com/blog/studio-notes" }, "datePublished": "2026-07-01T12:00:00.000Z", "dateModified": "2026-07-01T12:00:00.000Z" } ] } }

Ein fehlender oder unveröffentlichter Beitrag ergibt HTTP 404 mit {"error":"not_found"}.

Archive

Erstellen Sie Kategorie- und Schlagwortverzeichnisse aus der Antwort von /terms. Jeder Begriff verlinkt eine gefilterte Beitragsliste. Behalten Sie Sprache, Filter und Seitengröße beim Blättern bei. Das Antwortschema entspricht dem der Blogübersicht.

curl "$BASE/terms?language=en"
{ "categories": [ { "slug": "news", "name": "News", "count": 3 } ], "tags": [ { "slug": "design", "name": "Design", "count": 2 } ] }
curl "$BASE/posts?language=en&category=news&limit=1" curl "$BASE/posts?language=en&tag=design&limit=1"

Einzelbeitrag-Antwortvertrag

GET /posts/{slug} gibt { post } zurück mit:

  • id, slug, title, excerpt — Identität und Zusammenfassungstext.
  • html — der gerenderte, bereinigte Beitragstext. Wurzel-relative Links werden gegen die öffentliche URL Ihrer Website absolutiert. Kann direkt injiziert werden: strenge Tag-Allowlist, keine <script>-/<style>-/on*-Attribute.
  • blocks — das strukturierte Block-Array, falls Sie das Rendern dem Injizieren von html vorziehen.
  • metaTitle, metaDescription, keyphrase, categories, tags.
  • featuredImage, bodyImage — { url, width, height, alt?, caption? }.
  • og — { title, description, image }, fertig für Open-Graph-Tags.
  • author — { name, bio, avatarUrl, profileUrl, sameAs }, die reale Person, der die Website den Beitrag zuschreibt, oder null, wenn die Website für die Persona des Beitrags keinen Autor festgelegt hat. Es ist nie der Name der Persona. bio, avatarUrl und profileUrl können null sein; sameAs ist ein Array mit den URLs weiterer Profile des Autors und kann leer sein. Den Autor legen Sie im Kundenportal pro Persona und Website fest, siehe Was ist eine Persona?.
  • schema — ein Array von schema.org-JSON-LD-Objekten. Der erste Eintrag ist ein BlogPosting für den Beitrag: headline, description, image, @id und mainEntityOfPage aus der kanonischen URL des Beitrags, datePublished, dateModified und der Autor als Person (name, description, image, url, sameAs). Leere Felder werden weggelassen, ebenso author, wenn der Beitrag keinen Autor hat. Ein publisher fehlt bewusst: Den Organization-Knoten liefert Ihre Website. Danach folgen HowTo und FAQPage, wenn der Beitrag diese Abschnitte enthält. Wird außerhalb des Bands geliefert, da der Body-Sanitizer <script> entfernt — geben Sie für jeden Eintrag ein <script type="application/ld+json"> in Ihr Seiten-<head> aus, um für Rich Results in Frage zu kommen. Die entsprechenden Body-Abschnitte tragen die Klassen structura-howto / structura-faq für das Styling.
  • publishedAt, updatedAt — ISO 8601. updatedAt ist Ihr Revalidierungs-Signal.

Die Listenantwort gibt nur den Zusammenfassungs-Teilsatz zurück — ohne html, blocks, author oder schema.

Artikel-Markup und Byline

Wenn Sie jeden schema-Eintrag ausgeben, tragen Ihre Beitragsseiten ohne weiteren Aufwand Artikel- und Autoren-Markup, das Suchmaschinen für Rich Results nutzen können. Baut Ihre Website bereits einen eigenen Article- oder BlogPosting-Knoten, lassen Sie unseren weg, sonst meldet jede Seite zwei Artikel:

const jsonLd = post.schema.filter((entry) => entry["@type"] !== "BlogPosting");

Den Autor für Ihren eigenen Knoten nehmen Sie dann aus post.author.

Für eine sichtbare Byline zeigen Sie post.author.name, das Bild aus avatarUrl und die bio an und verlinken den Namen auf profileUrl, sofern gesetzt. Ist post.author null, lassen Sie die Byline weg.

Verwendung mit einem Framework

Lesen Sie den Cursor sowohl beim direkten Aufruf als auch beim Blättern aus der Seiten-URL. Blogübersicht und Archive verwenden dieselben API-Parameter.

  • Astro. Lesen Sie bei bedarfsgesteuert gerenderten .astro-Seiten vor dem Abruf der Beiträge Astro.url.searchParams. Lesen Sie den Cursor bei statischem Hosting im Browser. Astro 
  • Nuxt. Übergeben Sie eine reaktive Anfrage-URL an useFetch, damit eine Änderung der Routenparameter die gewählte Seite lädt. Nuxt 
  • SvelteKit. Lesen Sie bei serverseitigen Routen url.searchParams und den Archiv-Slug in der load-Funktion der Seite. Verwenden Sie das bereitgestellte fetch. SvelteKit 

Dieses Beispiel für den Next.js App Router lädt die erste Seite beim Build oder bei der Revalidierung.

// Next.js App Router — a blog index with ISR const BASE = process.env.STRUCTURA_DELIVERY_BASE; // from the Delivery API page export default async function BlogIndex() { const res = await fetch(`${BASE}/posts?language=en`, { next: { revalidate: 300 }, }); const { posts } = await res.json(); // Link each post using the site’s configured permalink pattern. }
// One post page — getStaticPaths-friendly const res = await fetch(`${BASE}/posts/${slug}`); const { post } = await res.json(); // inject post.html, emit post.schema entries as JSON-LD in <head> // (filter out the BlogPosting entry if you build your own Article node), // render a byline from post.author when it is not null

Antworten werden im CDN zwischengespeichert. Setups mit Polling sollten die Revalidierung an updatedAt knüpfen, statt jedes Mal neu zu rendern.

Weiterführende Seiten

Zuletzt geprüft am