API de entrega headless
Esta es una referencia para desarrolladores. Si estás configurando un espacio headless por primera vez, comienza con Crear un espacio headless.
Cada espacio headless sirve sus entradas publicadas desde una API de lectura pública, cacheable en CDN. No requiere autenticación ni clave de API — la API devuelve solo entradas publicadas (los borradores y las entradas programadas nunca aparecen), y un blog es público por definición.
La URL base de tu espacio — incluidos los identificadores de workspace y sitio — se muestra en la página Delivery API del sitio en el portal de cliente, junto con URLs de feed listas para usar por idioma. Todas las rutas que se indican a continuación son relativas a esa base.
Endpoints
| Ruta | Devuelve |
|---|---|
GET /posts | Entradas publicadas, las más recientes primero (solo campos de resumen) |
GET /posts/{slug} | Una entrada publicada, contrato completo (ver más abajo) |
GET /terms | Categorías y etiquetas con recuento de entradas |
Parámetros de consulta (/posts)
| Parámetro | Descripción |
|---|---|
language | Entradas en un idioma (p. ej. de). Cada idioma es un blog separado — una campaña por idioma. |
category | Filtrar por slug de categoría. Mutuamente exclusivo con tag. |
tag | Filtrar por slug de etiqueta. Mutuamente exclusivo con category. |
cursor | Página siguiente (más antigua) — pasa el nextCursor de la respuesta anterior. |
before | Página anterior (más reciente) — pasa el prevCursor de la respuesta. |
limit | Elementos por página; valor predeterminado y máximo 50. |
language se combina con category o tag:
/posts?language=de&category=news es el archivo “News” del blog en alemán.
/terms?language=de aplica el mismo ámbito a la taxonomía.
Paginación
Las respuestas de lista son bidireccionales: cada una devuelve nextCursor
(hacia entradas más antiguas) y prevCursor (hacia entradas más recientes).
Un cursor null significa que no hay más páginas en esa dirección — renderiza
cada página únicamente a partir de su token de URL, sin necesidad de mantener
un historial de cursores.
Ejemplos de solicitudes y esquemas de respuesta
Asigna a BASE la URL pública de lectura de tu sitio hasta el identificador del sitio incluido. Los esquemas OpenAPI describen los tipos de campo de los tres endpoints y cuáles admiten null.
Índice del blog
Usa los cursores devueltos como cadenas. Estas solicitudes muestran la primera página y las dos direcciones de navegación. Ofrece cada enlace solo cuando tenga 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
fiArtículo
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 inexistente o sin publicar devuelve HTTP 404 con {"error":"not_found"}.
Archivos
Usa la respuesta de /terms para crear los directorios de categorías y etiquetas. Cada término enlaza con una lista filtrada de entradas. Conserva el idioma, el filtro y el tamaño de página al seguir cualquiera de los cursores. La respuesta usa el mismo esquema que el índice del 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"Contrato de respuesta de entrada individual
GET /posts/{slug} devuelve { post } con:
id,slug,title,excerpt— identidad y texto de resumen.html— el contenido renderizado y saneado. Los enlaces relativos a la raíz se convierten en absolutos tomando como referencia la URL pública de tu sitio. Se puede inyectar tal cual: lista de etiquetas permitidas estricta, sin atributos<script>/<style>/on*.blocks— el array de bloques estructurado, si prefieres renderizar en lugar de inyectarhtml.metaTitle,metaDescription,keyphrase,categories,tags.featuredImage,bodyImage—{ url, width, height, alt?, caption? }.og—{ title, description, image }, listo para etiquetas Open Graph.author—{ name, bio, avatarUrl, profileUrl, sameAs }, el autor real al que el sitio atribuye la entrada, onullsi el sitio no tiene un autor definido para la persona de la entrada. Nunca es el nombre de la persona (la voz de escritura).bio,avatarUrlyprofileUrlpueden sernull;sameAses un array con las URL de otros perfiles del autor y puede estar vacío. El autor se define por persona y por sitio en el portal de cliente; consulta ¿Qué es una persona?.schema— un array de objetos JSON-LD de schema.org. El primer elemento es unBlogPostingde la entrada:headline,description,image,@idymainEntityOfPagea partir de la URL canónica de la entrada,datePublished,dateModifiedy el autor comoPerson(name,description,image,url,sameAs). Los campos vacíos se omiten, y tambiénauthorcuando la entrada no tiene autor. No incluyepublisher: el nodo Organization lo aporta tu sitio. Después siguenHowToyFAQPagecuando la entrada contiene esas secciones. Se entrega fuera de banda porque el saneador del contenido elimina<script>— emite un<script type="application/ld+json">por entrada en el<head>de tu página para ser elegible para resultados enriquecidos. Las secciones correspondientes del contenido llevan las clasesstructura-howto/structura-faqpara el estilo.publishedAt,updatedAt— ISO 8601.updatedAtes tu señal de revalidación.
La respuesta de lista devuelve solo el subconjunto de resumen — sin html,
blocks, author ni schema.
Marcado de artículo y firma del autor
Si emites todos los elementos de schema, las páginas de tus entradas incluyen
marcado de artículo y de autor que los buscadores pueden usar para resultados
enriquecidos, sin trabajo adicional. Si tu sitio ya genera su propio nodo
Article o BlogPosting, deja fuera el nuestro; si no, cada página declara dos
artículos:
const jsonLd = post.schema.filter((entry) => entry["@type"] !== "BlogPosting");Después toma el autor para tu propio nodo de post.author.
Para mostrar la firma, usa post.author.name, la imagen de avatarUrl y la
bio, y enlaza el nombre a profileUrl cuando exista. Si post.author es
null, omite la firma.
Consumo desde un framework
Lee el cursor de la URL de la página tanto en visitas directas como al navegar dentro del sitio. El índice del blog y cada archivo usan los mismos parámetros de la API.
- Astro. En una página .astro renderizada bajo demanda, lee
Astro.url.searchParamsantes de obtener las entradas. En alojamiento estático, lee el cursor en el navegador. Astro - Nuxt. Pasa una URL reactiva a
useFetchpara que los cambios en la consulta de la ruta carguen la página seleccionada. Nuxt - SvelteKit. En una ruta de servidor, lee
url.searchParamsy el slug del archivo en la funciónloadde la página. Usa elfetchque recibe la función. SvelteKit
Este ejemplo de Next.js App Router lee la primera página durante la compilación o la revalidación.
// 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 nullLas respuestas se almacenan en la caché de la CDN. Si consultas la API
periódicamente, vincula la revalidación a updatedAt en lugar de volver a
renderizar siempre.
Páginas relacionadas
- Crear un espacio headless
- API REST del plugin — el equivalente del lado de WordPress
Última verificación: