API de diffusion headless
Ceci est une référence développeur. Si vous configurez un espace headless pour la première fois, commencez par Créer un espace headless.
Chaque espace headless sert ses articles publiés depuis une API de lecture publique, compatible CDN et sans cache. Il n’y a ni authentification ni clé API — l’API retourne uniquement les articles publiés (les brouillons et les articles planifiés n’apparaissent jamais), et un blog est public par définition.
L’URL de base de votre espace — incluant les identifiants de votre espace de travail et de votre site — est affichée sur la page Delivery API de votre site dans le portail client, ainsi que des URL de flux prêts à l’emploi par langue. Tous les chemins ci-dessous sont relatifs à cette base.
Endpoints
| Route | Retourne |
|---|---|
GET /posts | Articles publiés, du plus récent au plus ancien (champs résumés uniquement) |
GET /posts/{slug} | Un article publié, contrat complet (voir ci-dessous) |
GET /terms | Catégories et tags avec le nombre d’articles |
Paramètres de requête (/posts)
| Paramètre | Description |
|---|---|
language | Articles dans une langue (ex. de). Chaque langue est un blog distinct — une campagne par langue. |
category | Filtrer par slug de catégorie. Exclusif avec tag. |
tag | Filtrer par slug de tag. Exclusif avec category. |
cursor | Page suivante (plus ancienne) — passez le nextCursor de la réponse précédente. |
before | Page précédente (plus récente) — passez le prevCursor de la réponse. |
limit | Éléments par page ; valeur par défaut et maximum : 50. |
language se cumule avec category ou tag :
/posts?language=de&category=news correspond aux archives « News » du blog
en allemand. /terms?language=de applique la même portée à la taxonomie.
Pagination
Les réponses de liste sont bidirectionnelles : chacune retourne nextCursor
(vers les articles plus anciens) et prevCursor (vers les articles plus
récents). Un curseur null signifie qu’il n’y a plus de pages dans cette
direction — affichez chaque page uniquement à partir de son jeton d’URL,
sans avoir besoin de conserver un historique de curseurs.
Exemples de requêtes et schémas de réponse
Affectez à BASE l’URL publique de lecture du site, identifiant du site inclus. Les schémas OpenAPI précisent les types des champs des trois endpoints et ceux qui acceptent null.
Index du blog
Transmettez les curseurs reçus sous forme de chaînes. Ces requêtes illustrent la première page et les deux sens de navigation. Affichez chaque lien uniquement si le curseur correspondant existe.
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
fiArticle
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"
}
]
}
}Un slug introuvable ou non publié renvoie HTTP 404 avec {"error":"not_found"}.
Archives
Utilisez la réponse de /terms pour créer les répertoires de catégories et d’étiquettes. Chaque terme mène à une liste filtrée d’articles. Conservez la langue, le filtre et la taille de page dans les deux sens de navigation. La réponse suit le même schéma que l’index du blog.
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"Contrat de réponse pour un article individuel
GET /posts/{slug} retourne { post } avec :
id,slug,title,excerpt— identité et texte de résumé.html— le contenu rendu et assaini. Les liens relatifs à la racine sont absolutisés par rapport à l’URL publique de votre site. Peut être injecté tel quel : liste d’autorisation stricte de balises, pas d’attributs<script>/<style>/on*.blocks— le tableau de blocs structurés, si vous préférez le rendu à l’injection dehtml.metaTitle,metaDescription,keyphrase,categories,tags.featuredImage,bodyImage—{ url, width, height, alt?, caption? }.og—{ title, description, image }, prêt pour les balises Open Graph.author—{ name, bio, avatarUrl, profileUrl, sameAs }, la personne réelle à qui le site attribue l’article, ounullsi le site n’a pas défini d’auteur pour la persona de l’article. Ce n’est jamais le nom de la persona.bio,avatarUrletprofileUrlpeuvent valoirnull;sameAsest un tableau des URL des autres profils de l’auteur et peut être vide. L’auteur se définit par persona et par site dans le portail client, voir Qu’est-ce qu’une persona ?.schema— un tableau d’objets schema.org JSON-LD. La première entrée est unBlogPostingpour l’article :headline,description,image,@idetmainEntityOfPaged’après l’URL canonique de l’article,datePublished,dateModified, et l’auteur sous forme dePerson(name,description,image,url,sameAs). Les champs vides sont omis, tout commeauthorquand l’article n’a pas d’auteur. Il n’y a pas depublisher: le nœud Organization relève de votre site. Les entréesHowToetFAQPagesuivent lorsque l’article contient ces sections. Fourni hors bande car l’assainisseur de contenu supprime<script>— émettez un<script type="application/ld+json">par entrée dans le<head>de votre page pour l’éligibilité aux résultats enrichis. Les sections correspondantes du contenu portent les classesstructura-howto/structura-faqpour la mise en forme.publishedAt,updatedAt— ISO 8601.updatedAtest votre signal de revalidation.
La réponse de liste retourne uniquement le sous-ensemble résumé — sans
html, blocks, author ni schema.
Balisage d’article et signature de l’auteur
Si vous émettez toutes les entrées de schema, vos pages d’article portent un
balisage d’article et d’auteur que les moteurs de recherche peuvent exploiter
pour les résultats enrichis, sans travail supplémentaire. Si votre site
construit déjà son propre nœud Article ou BlogPosting, laissez le nôtre de
côté, sinon chaque page déclare deux articles :
const jsonLd = post.schema.filter((entry) => entry["@type"] !== "BlogPosting");Prenez ensuite l’auteur de votre propre nœud dans post.author.
Pour une signature visible, affichez post.author.name, l’image avatarUrl
et la bio, et liez le nom à profileUrl lorsqu’il est renseigné. Quand
post.author vaut null, n’affichez pas de signature.
Consommation depuis un framework
Lisez le curseur dans l’URL de la page aussi bien en accès direct que lors de la navigation sur le site. L’index du blog et chaque archive utilisent les mêmes paramètres de l’API.
- Astro. Dans une page .astro rendue à la demande, lisez
Astro.url.searchParamsavant de charger les articles. Sur un hébergement statique, lisez le curseur dans le navigateur. Astro - Nuxt. Passez une URL réactive à
useFetchpour que la page sélectionnée se charge lorsque les paramètres de requête changent. Nuxt - SvelteKit. Dans une route rendue côté serveur, lisez
url.searchParamset le slug de l’archive dans la fonctionloadde la page. Utilisez lefetchfourni. SvelteKit
Cet exemple pour le Next.js App Router charge la première page au moment du build ou de la revalidation.
// 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 nullLes réponses sont mises en cache par le CDN. Si vous interrogez l’API à
intervalles réguliers, basez la revalidation sur updatedAt plutôt que de
refaire le rendu à chaque fois.
Pages connexes
- Créer un espace headless
- API REST de l’extension — l’équivalent côté WordPress
Dernière vérification :