API de publicación

RankBloom escribe contenido SEO para los sitios web que conectas. La API de publicación es la vía por la que ese contenido terminado sale de RankBloom y llega a donde tú quieras: un sitio WordPress, un CMS, una plataforma de automatización o tu propio código.

Es la misma API que hay detrás del plugin oficial de WordPress y de las integraciones con Zapier y Make.

URL base

https://app.getrankbloom.com/api/publish

Autenticación

Cada solicitud lleva un token de conexión. Créalo en RankBloom, en Conexiones: selecciona el sitio, elige la plataforma y haz clic en Crear conexión. El token se muestra una sola vez y se guarda solo como hash, así que guarda una copia al crearlo.

Cada token está limitado a un único sitio. Envíalo en cualquiera de estas cabeceras:

Authorization: Bearer rb_live_xxxxxxxx
X-RankBloom-Token: rb_live_xxxxxxxx
X-API-KEY: rb_live_xxxxxxxx

Se aceptan las tres porque los hostings compartidos y gestionados suelen eliminar Authorization, y algunas plataformas de automatización envían una cabecera X-API-KEY de forma predeterminada.

Nunca pongas el token en la cadena de consulta. Quedaría registrado en los logs de acceso y en todos los proxies del camino. La API no lo lee de ahí.

Revocar una conexión surte efecto de inmediato. Los tokens revocados y los desconocidos devuelven la misma respuesta, así que nadie puede usar la diferencia para sondear tokens válidos.

Endpoints

GET /v1/ping

Verifica un token e indica a qué está asociado. Úsalo como prueba de conexión.

curl https://app.getrankbloom.com/api/publish/v1/ping \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "label": "Example Site",
  "connection": { "id": "…", "name": "Make — Example Site", "platform": "make" },
  "site": { "id": "…", "name": "Example Site", "url": "https://example.com" }
}

label es un nombre sencillo y legible para la conexión. Las plataformas de automatización lo usan para etiquetar la cuenta conectada.

GET /v1/posts

Posts recientes del sitio conectado, del más nuevo al más antiguo. Solo lectura: nunca cambia el estado, así que es seguro consultarlo de forma periódica.

Parámetro	Tipo	Por defecto	Notas
`limit`	integer	25	Máximo 100
`offset`	integer	0	Omite este número de posts
`since`	ISO 8601	—	Solo posts creados en ese momento o después

curl "https://app.getrankbloom.com/api/publish/v1/posts?limit=100&offset=0" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "count": 46,
  "limit": 100,
  "offset": 0,
  "posts": [ … ]
}

Paginación. Aumenta offset en limit para recorrer el archivo hacia atrás. No hay recuento total: una página más corta que limit significa que has llegado al final. Los resultados se ordenan por fecha de creación y luego por id, así que la paginación se mantiene estable aunque dos posts compartan la misma marca de tiempo.

POST /v1/status

Dile a RankBloom qué pasó con un post. Esto es lo que convierte «lo entregamos» en «está publicado» y evita que el post se vuelva a ofrecer.

curl -X POST https://app.getrankbloom.com/api/publish/v1/status \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "b86cbffe-…",
    "status": "delivered",
    "external_url": "https://example.com/my-post",
    "external_id": "123"
  }'

Campo	Obligatorio	Notas
`post_id`	sí	El `id` de `/v1/posts`
`status`	sí	`delivered`, `failed` o `skipped`
`external_url`	no	Dónde se publicó
`external_id`	no	El id propio del sistema remoto
`error`	no	Por qué falló, si falló

Un token solo puede informar sobre posts que pertenezcan a su propio sitio.

El payload del post

Un único formato canónico, versionado con contract_version.

Campo	Tipo	Notas
`id`	string	Estable. Úsalo como clave de idempotencia
`title`, `slug`, `excerpt`	string	`slug` es el definitivo, ya sin duplicados
`content_html`, `content_md`	string	El cuerpo, en ambos formatos
`meta_title`, `meta_description`	string	Metadatos SEO
`primary_keyword`, `keywords`, `category`, `tags`	string / array	Taxonomía
`canonical_url`	string	Canonical, cuando está definida
`schema_json_ld`	object	Ya parseado, nunca una cadena JSON
`featured_image_url`	string	Imagen alojada, lista para usar
`audio_url`	string	Narración, cuando el post la tiene
`audio_duration_seconds`, `audio_voice`	number / string	Detalle de la narración
`status`	string	`published` o `draft`
`author`, `author_title`, `author_url`	string	Autoría
`created_at`, `published_at`	ISO 8601	Marcas de tiempo

Todas las claves están siempre presentes. Un valor que no aplica se devuelve como null — nunca se omite. Un post sin narración simplemente tiene audio_url: null; ese es el caso normal, no un error. Programa tu integración para esperar nulls en lugar de claves ausentes.

El contrato es solo aditivo. Los campos nunca se renombran, ni cambian de tipo, ni se eliminan, porque las integraciones ya en producción seguirán pidiendo la versión 1 indefinidamente. Un cambio incompatible se publicaría como una versión nueva, servida junto a esta.

Errores

Los errores devuelven el estado HTTP correspondiente y un cuerpo JSON con un mensaje legible.

{ "ok": false, "error": "Invalid or revoked connection token." }

Estado	Significado
`400`	Falta un campo obligatorio o tiene un formato incorrecto
`401`	Token ausente, desconocido o revocado
`404`	El post no pertenece a esta conexión

Integraciones listas para usar

No hace falta escribir código. La misma API ya está integrada en:

WordPress — el plugin oficial de Get RankBloom. Conecta con un clic, sin pegar ningún token.
Make — una app personalizada con Watch Posts como disparador y Mark Post as Published como acción.
Zapier — New Post como disparador y Mark Post as Published como acción.

Soporte

¿Tienes dudas sobre la API o algo no se comporta como está documentado? Escribe a support@getrankbloom.com.