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
| Route | Gibt zurück |
|---|---|
GET /posts | Veröffentlichte Beiträge, neueste zuerst (nur Zusammenfassungsfelder) |
GET /posts/{slug} | Ein veröffentlichter Beitrag, vollständiger Vertrag (siehe unten) |
GET /terms | Kategorien und Tags mit Beitragsanzahl |
Query-Parameter (/posts)
| Parameter | Beschreibung |
|---|---|
language | Beiträge in einer Sprache (z. B. de). Jede Sprache ist ein separater Blog — eine Kampagne pro Sprache. |
category | Filtern nach Kategorie-slug. Schließt sich gegenseitig mit tag aus. |
tag | Filtern nach Tag-slug. Schließt sich gegenseitig mit category aus. |
cursor | Nächste (ältere) Seite — die nextCursor der vorherigen Antwort übergeben. |
before | Vorherige (neuere) Seite — die prevCursor der Antwort übergeben. |
limit | Einträ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
fiEinzelbeitrag
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 vonhtmlvorziehen.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, odernull, wenn die Website für die Persona des Beitrags keinen Autor festgelegt hat. Es ist nie der Name der Persona.bio,avatarUrlundprofileUrlkönnennullsein;sameAsist 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 einBlogPostingfür den Beitrag:headline,description,image,@idundmainEntityOfPageaus der kanonischen URL des Beitrags,datePublished,dateModifiedund der Autor alsPerson(name,description,image,url,sameAs). Leere Felder werden weggelassen, ebensoauthor, wenn der Beitrag keinen Autor hat. Einpublisherfehlt bewusst: Den Organization-Knoten liefert Ihre Website. Danach folgenHowToundFAQPage, 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 Klassenstructura-howto/structura-faqfür das Styling.publishedAt,updatedAt— ISO 8601.updatedAtist 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.searchParamsund den Archiv-Slug in derload-Funktion der Seite. Verwenden Sie das bereitgestelltefetch. 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 nullAntworten werden im CDN zwischengespeichert. Setups mit Polling sollten die
Revalidierung an updatedAt knüpfen, statt jedes Mal neu zu rendern.
Weiterführende Seiten
- Einen Headless-Space erstellen
- Plugin REST-API — das Gegenstück auf der WordPress-Seite
Zuletzt geprüft am