Skip to Content
ReferenciaAPI de entrega headless

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

RutaDevuelve
GET /postsEntradas publicadas, las más recientes primero (solo campos de resumen)
GET /posts/{slug}Una entrada publicada, contrato completo (ver más abajo)
GET /termsCategorías y etiquetas con recuento de entradas

Parámetros de consulta (/posts)

ParámetroDescripción
languageEntradas en un idioma (p. ej. de). Cada idioma es un blog separado — una campaña por idioma.
categoryFiltrar por slug de categoría. Mutuamente exclusivo con tag.
tagFiltrar por slug de etiqueta. Mutuamente exclusivo con category.
cursorPágina siguiente (más antigua) — pasa el nextCursor de la respuesta anterior.
beforePágina anterior (más reciente) — pasa el prevCursor de la respuesta.
limitElementos 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 fi

Artí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 inyectar html.
  • 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, o null si 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, avatarUrl y profileUrl pueden ser null; sameAs es 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 un BlogPosting de la entrada: headline, description, image, @id y mainEntityOfPage a partir de la URL canónica de la entrada, datePublished, dateModified y el autor como Person (name, description, image, url, sameAs). Los campos vacíos se omiten, y también author cuando la entrada no tiene autor. No incluye publisher: el nodo Organization lo aporta tu sitio. Después siguen HowTo y FAQPage cuando 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 clases structura-howto / structura-faq para el estilo.
  • publishedAt, updatedAt — ISO 8601. updatedAt es 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.searchParams antes de obtener las entradas. En alojamiento estático, lee el cursor en el navegador. Astro 
  • Nuxt. Pasa una URL reactiva a useFetch para que los cambios en la consulta de la ruta carguen la página seleccionada. Nuxt 
  • SvelteKit. En una ruta de servidor, lee url.searchParams y el slug del archivo en la función load de la página. Usa el fetch que 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 null

Las 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

Última verificación: