Skip to Content
RéférenceAPI de diffusion headless

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

RouteRetourne
GET /postsArticles 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 /termsCatégories et tags avec le nombre d’articles

Paramètres de requête (/posts)

ParamètreDescription
languageArticles dans une langue (ex. de). Chaque langue est un blog distinct — une campagne par langue.
categoryFiltrer par slug de catégorie. Exclusif avec tag.
tagFiltrer par slug de tag. Exclusif avec category.
cursorPage suivante (plus ancienne) — passez le nextCursor de la réponse précédente.
beforePage 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 fi

Article

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 de html.
  • 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, ou null si 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, avatarUrl et profileUrl peuvent valoir null ; sameAs est 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 un BlogPosting pour l’article : headline, description, image, @id et mainEntityOfPage d’après l’URL canonique de l’article, datePublished, dateModified, et l’auteur sous forme de Person (name, description, image, url, sameAs). Les champs vides sont omis, tout comme author quand l’article n’a pas d’auteur. Il n’y a pas de publisher : le nœud Organization relève de votre site. Les entrées HowTo et FAQPage suivent 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 classes structura-howto / structura-faq pour la mise en forme.
  • publishedAt, updatedAt — ISO 8601. updatedAt est 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.searchParams avant de charger les articles. Sur un hébergement statique, lisez le curseur dans le navigateur. Astro 
  • Nuxt. Passez une URL réactive à useFetch pour 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.searchParams et le slug de l’archive dans la fonction load de la page. Utilisez le fetch fourni. 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 null

Les 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

Dernière vérification :