API de publication

RankBloom rédige du contenu SEO pour les sites que vous y connectez. L’API de publication est la porte par laquelle ce contenu fini quitte RankBloom pour rejoindre sa destination — un site WordPress, un CMS, une plateforme d’automatisation ou votre propre code.

C’est la même API qui alimente l’extension WordPress officielle et les intégrations Zapier et Make.

URL de base

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

Authentification

Chaque requête doit inclure un token de connexion. Créez-en un dans RankBloom, sous Connexions : sélectionnez le site, choisissez la plateforme, puis cliquez sur Créer une connexion. Le token n’est affiché qu’une seule fois et n’est conservé que sous forme de hash : gardez-en une copie au moment de le créer.

Un token est limité à un seul site. Envoyez-le dans l’un de ces en-têtes :

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

Les trois sont acceptés parce que les hébergeurs mutualisés et infogérés suppriment souvent Authorization, et certaines plateformes d’automatisation envoient un en-tête X-API-KEY par défaut.

Ne mettez jamais le token dans une chaîne de requête. Il finirait dans les journaux d’accès et chez chaque proxy sur le trajet. De toute façon, l’API ne l’y lit pas.

La révocation d’une connexion prend effet immédiatement. Les tokens révoqués et les tokens inconnus renvoient la même réponse : un appelant ne peut donc pas exploiter la différence pour deviner des tokens valides.

Endpoints

GET /v1/ping

Vérifie un token et indique à quoi il est rattaché. À utiliser comme test de connexion.

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 est un nom simple et lisible pour la connexion. Les plateformes d’automatisation s’en servent pour étiqueter le compte connecté.

GET /v1/posts

Les articles récents du site connecté, du plus récent au plus ancien. En lecture seule — l’appel ne modifie jamais l’état, vous pouvez donc l’interroger à intervalle régulier sans risque.

Paramètre	Type	Par défaut	Notes
`limit`	integer	25	100 maximum
`offset`	integer	0	Ignorer ce nombre d’articles
`since`	ISO 8601	—	Uniquement les articles créés à cette date ou aprè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": [ … ]
}

Pagination. Augmentez offset de limit pour remonter dans les archives. Il n’y a pas de total : une page plus courte que limit signifie que vous avez atteint la fin. Les résultats sont triés par date de création puis par id, si bien que la pagination reste stable même quand deux articles partagent le même horodatage.

POST /v1/status

Indiquez à RankBloom ce qu’est devenu un article. C’est ce qui transforme « nous l’avons transmis » en « il est en ligne », et ce qui empêche l’article d’être proposé à nouveau.

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"
  }'

Champ	Obligatoire	Notes
`post_id`	oui	Champ `id` renvoyé par `/v1/posts`
`status`	oui	`delivered`, `failed` ou `skipped`
`external_url`	non	L’URL de publication
`external_id`	non	L’identifiant propre au système distant
`error`	non	La raison de l’échec, le cas échéant

Un token ne peut signaler que des articles appartenant à son propre site.

Le format d’un article

Un format canonique unique, versionné par contract_version.

Champ	Type	Notes
`id`	string	Stable. À utiliser comme clé d’idempotence
`title`, `slug`, `excerpt`	string	`slug` est la version finale, dédoublonnée
`content_html`, `content_md`	string	Le corps, dans les deux formats
`meta_title`, `meta_description`	string	Métadonnées SEO
`primary_keyword`, `keywords`, `category`, `tags`	string / array	Taxonomie
`canonical_url`	string	URL canonique, si définie
`schema_json_ld`	object	Objet parsé, jamais une chaîne JSON
`featured_image_url`	string	Image hébergée, prête à l’emploi
`audio_url`	string	Narration, si l’article en a une
`audio_duration_seconds`, `audio_voice`	number / string	Détail de la narration
`status`	string	`published` ou `draft`
`author`, `author_title`, `author_url`	string	Signature
`created_at`, `published_at`	ISO 8601	Horodatages

Toutes les clés sont toujours présentes. Une valeur non applicable vaut null — elle n’est jamais omise. Un article sans narration a simplement audio_url: null ; c’est le cas normal, pas une erreur. Concevez votre intégration pour attendre des valeurs nulles plutôt que des clés absentes.

Le contrat est purement additif. Les champs ne sont jamais renommés, retypés ni supprimés, car des intégrations déjà en production continueront de demander la version 1 indéfiniment. Une rupture de compatibilité serait publiée comme une nouvelle version, servie en parallèle de celle-ci.

Erreurs

Les erreurs renvoient le statut HTTP correspondant et un corps JSON contenant un message lisible.

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

Statut	Signification
`400`	Un champ obligatoire est absent ou mal formé
`401`	Token absent, inconnu ou révoqué
`404`	L’article n’appartient pas à cette connexion

Intégrations prêtes à l’emploi

Vous n’avez pas besoin d’écrire de code. La même API est déjà encapsulée pour :

WordPress — l’extension officielle Get RankBloom. Connexion en un clic, aucun token à coller.
Make — une application dédiée avec Watch Posts comme déclencheur et Mark Post as Published comme action.
Zapier — New Post comme déclencheur et Mark Post as Published comme action.

Assistance

Une question sur l’API, ou un comportement qui ne correspond pas à la doc ? Écrivez à support@getrankbloom.com.