API de lectura
Una API de contenido SEO sobre cada artículo que has planificado.
La API responde a la pregunta que hace un informe: qué publicamos, dónde, en qué idioma y qué dice el artículo. Un endpoint por necesidad, una forma fija, nada que instalar — y ninguna forma de que una integración escriba en tu contenido.
Leer la referencia de la APIJSON sobre HTTPSClave Bearer o x-api-keySolo lectura, siempre
¿Qué le puedes pedir a la API de contenido?
Dos endpoints, cinco parámetros, un sobre. Esa es toda la superficie — y por eso no hay ninguna librería cliente que mantener actualizada.
La versión corta
- Dos endpoints: una lista de artículos y un artículo concreto por su id numérico o por su slug: prefijo y slug.
- Los filtros son website, status, language, limit (por defecto 100, máximo 200) y offset.
- Cada artículo devuelve las mismas 13 claves de primer nivel; un campo que aún no se ha generado es una cadena vacía en vez de faltar.
- La autenticación es una sola clave de cuenta, enviada como token Bearer o en una cabecera x-api-key; el límite es de 120 peticiones por minuto.
- Es de solo lectura. Nada en la API puede cambiar un artículo, una fecha ni un sitio.
- GET /api/v2/posts
- Todos los artículos de la cuenta, de más nuevo a más antiguo, con metadatos de paginación. El tamaño de página es 100 por defecto y acepta hasta 200; offset recorre el resto.
- GET /api/v2/posts/{id}
- Un artículo por su id numérico, o por slug como `slug:tu-articulo`, para que un CMS pueda buscarlo por la URL que ya conoce.
- ?website=<domain>
- Acota a un solo sitio — el dominio principal o el del blog, sin distinguir mayúsculas. El filtro se aplica antes del recuento, así que la paginación sigue siendo correcta.
- ?status=published
- El estado se compara de forma exacta: draft, pending_approval, published, unpublished, in_progress, failed_review. Sin filtrar, los recibes todos — incluidos los que siguen esperando.
- ?language=de
- Una sola línea editorial. Útil cuando el mismo tema existe en varios mercados y solo uno de ellos pertenece a este informe.
- 120 peticiones / minuto
- Por cuenta, con una cabecera Retry-After cuando te pasas. Suficiente para una sincronización nocturna y una búsqueda interna en vivo; no es un endpoint para scrapear.
Dos rutas, dos formas
/api/v2/posts es la ruta actual, y /api/posts es un alias suyo. /api/v1/posts sigue sirviendo la forma plana original, congelada, para que una integración existente siga funcionando; los clientes nuevos deberían empezar en v2. Solo cambia el objeto del artículo — autenticación, filtros, códigos de estado y paginación son idénticos.
La referencia completa
Cada parámetro, cada campo del payload y cada código de error — con ejemplos que puedes copiar — está en la referencia de abajo. Esta página es el paseo; esa es el contrato. referencia de la API de posts
Cómo se ve un artículo al viajar por la red.
Trece claves de primer nivel, todas presentes siempre. Tres agrupan los campos que van juntos, y el artículo viaja con sus metadatos, así que quien consume la API nunca necesita una segunda llamada para saber si un artículo está publicado.
/api/v2/posts?status=published&limit=1Authorization: Bearer xt4b_••••••••••••{
"data": [
{
"id": "57",
"status": "published",
"slug": "seo-content-cost-per-article",
"title": "¿Cuánto cuesta el contenido SEO por artículo?",
"meta": {
"title": "¿Cuánto cuesta el contenido SEO por artículo?",
"description": "Three pricing models and what each one hides."
},
"searchIntent": "commercial",
"keywords": {
"primary": "cuanto cuesta el contenido seo",
"secondary": ["seo content pricing"]
},
"images": { "cover": "https://cdn.xt4b.com/…/cover.svg" },
"language": "es",
"website": "xt4b.com",
"publishedAt": "2026-09-11T09:00:04.118Z"
}
],
"pagination": { "limit": 1, "offset": 0, "total": 7 }
}La respuesta es un sobre con data y pagination. Un artículo concreto devuelve el mismo objeto dentro de data, así que un único parser sirve para las dos llamadas.
Los campos que la pipeline aún no ha producido son cadenas vacías en vez de faltar: un artículo planificado tiene título, metadatos, intención y palabras clave, y ni markdown, ni portada, ni fecha de publicación. Un cliente puede pintar esa fila sin una sola condición para claves ausentes.
La forma es un contrato, no una comodidad. Es lo que leen el blog de Xt4b y sus paneles de Search Console, así que una columna nueva en la base de datos no puede convertirse sin avisar en un campo nuevo de tu integración.
El artículo, y el registro que lo rodea.
La mitad del payload es lo que ve un lector; la otra mitad es la trazabilidad que necesita un editor o un informe.
El artículo
- title — el titular con el que se publica el artículo
- meta.title y meta.description — escritos para la SERP, no copiados del cuerpo
- markdown — el artículo en su fuente, que es lo que editas
- html — el mismo artículo renderizado por el publicador, con los anclajes de los encabezados incluidos
El registro
- id y slug — claves estables en forma de cadena, y la URL en la que vive el artículo
- status — en qué punto de la pipeline está el artículo, no solo si está publicado o no
- website y language — qué sitio, qué mercado
- publishedAt — marca de tiempo ISO, vacía mientras sigue planificado
- keywords.primary, keywords.secondary y searchIntent — el brief con el que se escribió
- images.cover — la portada generada
De cero a tu primera fila.
Cuatro pasos, y el cuarto es una línea de curl que puedes pegar en un terminal o en un cron.
- 01
Crea una cuenta y conecta un sitio
La API es una ventana a tus propios artículos, así que necesita un sitio y un plan detrás. El análisis gratuito te muestra las consultas que le faltan a un sitio antes de que conectes nada.
- 02
Copia la clave desde Ajustes
Una clave por cuenta, visible en la página de ajustes. Regenerarla revoca la anterior al instante, y esa es toda la historia de rotación — no hay client id, ni secreto, ni URL de callback.
- 03
Envíala como cabecera
`Authorization: Bearer <key>` o `x-api-key: <key>`. Cualquiera de las dos funciona en todos los endpoints, así que un script y una herramienta de navegador pueden usar la que les resulte más simple.
- 04
Pide lo que necesitas
Empieza con `?status=published&limit=50` y luego acota con `website` y `language` cuando ya conozcas la forma. Pagina con `offset` en vez de pedir los artículos de uno en uno.
Tres llamadas, para copiar y pegar.
La primera devuelve una página de artículos publicados, la segunda busca uno por el slug de su URL y la tercera pregunta qué sigue esperando aprobación.
Lista lo publicado, un sitio a la vez
curl "https://xt4b.com/api/v2/posts?website=xt4b.com\ &status=published&limit=50" \ -H "Authorization: Bearer $XT4B_API_KEY"
Un artículo, por el slug de su URL
curl "https://xt4b.com/api/v2/posts/\ slug:seo-content-cost-per-article" \ -H "x-api-key: $XT4B_API_KEY"
Qué está esperando una decisión
curl "https://xt4b.com/api/v2/posts?status=draft\ &language=de&limit=100&offset=0" \ -H "Authorization: Bearer $XT4B_API_KEY"
El sobre de error
{
"error": {
"code": "rate_limited",
"message": "Too many requests — retry after 12s."
}
}Qué se construye con ella.
Las cuatro integraciones que salen primero, en el orden en que suelen construirse.
- 01
Un informe que se construye solo
Pide los artículos con status=published una vez por noche y escribe las filas en tu panel. Sin scrapear tu propio blog ni transcribir hojas de cálculo.
- 02
Tu CMS como destino
Si el blog vive en otro sitio, toma el markdown (o el HTML renderizado), los metadatos y las imágenes, y publícalo tú. La API es de solo lectura, así que nada de aquí puede sobrescribir lo que escribieron tus editores.
- 03
Un buscador interno que es tuyo
Filtra por sitio e idioma para construir un buscador o un bloque de artículos relacionados sobre tu propio archivo — incluidos los que siguen en borrador.
- 04
Una cola de control de calidad
Pide status=draft o failed_review y revisa lo que produjo la pipeline antes de que salga, con tus propias herramientas en vez de las nuestras.
Lo que la API no es.
Merece la pena decirlo claro, porque una API de lectura se sobrepromete con facilidad.
- No es un endpoint de generación
- No hay ningún POST que pida un artículo. El contenido lo planifica y lo escribe la pipeline contra un plan, y la API informa del resultado.
- No es un endpoint de publicación
- Nada de lo que envíes puede cambiar un artículo, una fecha ni un sitio. Si un cliente quiere publicar a través de su propio CMS, obtiene el artículo y publica allí — el fallo de una mala integración es un artículo que falta, nunca uno equivocado.
- No hay claves por sitio
- Una clave por cuenta, con ?website= como filtro. Más simple de rotar, y significa que la integración de una agencia se configura una vez en vez de por cliente.
- No es una promesa de posicionamiento
- Informa de lo que se publicó y de lo que muestra una Search Console conectada. No puede informar de una posición que aún no existe, y nada de esto garantiza tráfico ni ingresos — el posicionamiento, el tráfico y los ingresos no los garantiza esta API ni ninguna otra.
Más sobre contenido
- Contenido SEO multilingüe
Un idioma es una línea editorial, no una traducción de tus páginas inglesas.
- Blog alojado
Un blog en tu propio dominio detrás de un registro DNS, mantenido por nosotros.
- Para mercados multilingües
Qué mercado abrir después, y cuánto cuesta.
- llms.txt
El archivo de resumen para modelos de lenguaje, y qué contiene el nuestro.
Preguntas que hacen los desarrolladores.
Incluidas las dos sobre lo que se niega a hacer.
¿Hay algún endpoint que escriba o publique?
No. La API es de solo lectura por diseño: expone lo que la pipeline ha planificado y publicado, y nada en ella puede cambiar un artículo, una fecha ni un sitio. La publicación ocurre en el panel, donde la decisión la toma una persona.
¿Cómo funciona la autenticación?
Una clave por cuenta, visible en tus ajustes, enviada como `Authorization: Bearer <key>` o en una cabecera `x-api-key`. Regenerar la clave revoca la anterior al instante, y no hay baile de OAuth, ni client secret, ni nada que instalar.
¿Necesito un SDK?
No. Es JSON sobre HTTPS con un juego de filtros y un sobre — una llamada fetch en cualquier lenguaje, o una línea de curl en un cron. La forma de la respuesta es fija: todas las claves están presentes en todos los artículos, y los campos que aún no se han generado llegan como null en vez de faltar.
¿Por qué se devuelven el markdown y el HTML renderizado?
Porque casi todo el que consume la API necesita uno de los dos. El markdown es lo que editas y guardas; el HTML es el artículo tal como lo renderiza el publicador, con anclajes en los encabezados y enlaces saneados, para que un sitio pueda servir un artículo sin parsear markdown. Ninguno se deriva en el momento de la petición: los dos se leen de la fila almacenada.
¿La clave ve todos los sitios de la cuenta?
Sí — las claves son por cuenta, y los sitios se filtran con ?website=. Para una agencia eso significa una integración para todos sus clientes, con el filtro de sitio como lo único que cambia por informe.
¿Qué pasa cuando alcanzo el límite de peticiones?
Recibes un 429 con una cabecera Retry-After, y el contador es por cuenta en una ventana fija de un minuto. Pagina con limit y offset en vez de lanzar una petición por artículo: limit acepta hasta 200.
¿Cómo consigo una clave de API?
Se genera para ti: crea una cuenta y la clave aparece en la página de ajustes, lista para copiar. No hay formulario de solicitud, ni cliente OAuth que registrar, ni claves por sitio que repartir.
¿Puedo filtrar por rango de fechas?
No — los filtros son website, status, language, limit y offset. Los artículos llegan de más nuevo a más antiguo, así que una ventana de fechas es paginar: toma 200 cada vez y para cuando publishedAt sea anterior a la ventana que te interesa. Es deliberado: un filtro de fechas a medias sería peor que un paginado honesto.
¿La API devuelve artículos que aún no están publicados?
Sí, salvo que los filtres. Una lectura sin filtros devuelve todos los artículos con su estado, incluidos borradores, los que esperan aprobación y los que fallaron la revisión — que es lo que hace posible una cola de control de calidad. La mayoría de las integraciones de informes empiezan con ?status=published.
¿Hay sandbox o modo de prueba?
No. Hay una API y una clave. Como la API es de solo lectura, apuntarla a una cuenta real es inofensivo: lo peor que puede hacer un error es devolverte filas que no necesitabas.
¿Cómo son los errores?
El mismo sobre que los datos: un objeto `error` con un `code` legible por máquina y un mensaje — invalid_api_key (401), invalid_post_id (400), post_not_found (404), rate_limited (429). Nada devuelve una cadena suelta, así que un cliente puede ramificar por el código en vez de parsear prosa.
¿Puedo obtener los datos sin usar el blog alojado?
Ese es el motivo de publicar la API. El blog es el destino por defecto porque elimina del todo el trabajo de integración, pero los mismos artículos están disponibles como datos, así que un CMS existente, un build de sitio estático o un almacén de datos pueden ser el destino.
Una clave, todos los sitios
Publica en tu propio dominio, léelo como datos.
Crea una cuenta y conecta un sitio: la pipeline produce los artículos, el blog los sirve y la API te entrega las filas para demostrarlo.
Markdown y HTML renderizado120 peticiones por minuto3 días gratis, sin tarjeta