API di pubblicazione

RankBloom scrive contenuti SEO per il blog dei siti che gli colleghi. L’API di pubblicazione è il modo in cui quei contenuti finiti escono da RankBloom e arrivano dove vuoi tu: un sito WordPress, un CMS, una piattaforma di automazione o il tuo codice.

È la stessa API che sta dietro al plugin ufficiale per WordPress e alle integrazioni Zapier e Make.

URL di base

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

Autenticazione

Ogni richiesta include un token di connessione. Creane uno in RankBloom, alla voce Connessioni: seleziona il sito, scegli la piattaforma e fai clic su Crea connessione. Il token viene mostrato una sola volta e conservato solo come hash: quando lo crei, salvane una copia.

Ogni token vale per un solo sito. Invialo in uno qualsiasi di questi header:

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

Ne accettiamo tre perché gli hosting condivisi e gestiti rimuovono spesso Authorization, e alcune piattaforme di automazione inviano un header X-API-KEY per impostazione predefinita.

Non mettere mai il token in una query string. Finirebbe nei log di accesso e in ogni proxy lungo il percorso. L’API non lo legge da lì.

La revoca di una connessione ha effetto immediato. I token revocati e quelli sconosciuti restituiscono la stessa risposta, così nessuno può sfruttare la differenza per scovare token validi.

Endpoint

GET /v1/ping

Verifica un token e indica a che cosa è collegato. Usalo come test di connessione.

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 è un nome semplice e leggibile della connessione. Le piattaforme di automazione lo usano per etichettare l’account collegato.

GET /v1/posts

I post recenti del sito collegato, dal più recente. Sola lettura: non cambia mai nulla, quindi puoi interrogarlo a intervalli regolari senza rischi.

Parametro	Tipo	Predefinito	Note
`limit`	integer	25	Massimo 100
`offset`	integer	0	Salta questo numero di post
`since`	ISO 8601	—	Solo i post creati da questo momento in poi

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": [ … ]
}

Paginazione. Aumenta offset di limit per scorrere l’archivio a ritroso. Non esiste un conteggio totale: una pagina più corta di limit significa che sei arrivato alla fine. I risultati sono ordinati per data di creazione e poi per id, quindi la paginazione resta stabile anche quando due post hanno lo stesso timestamp.

POST /v1/status

Comunica a RankBloom che fine ha fatto un post. È ciò che trasforma «lo abbiamo consegnato» in «è online» e impedisce che il post venga riproposto.

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	Obbligatorio	Note
`post_id`	sì	Il campo `id` restituito da `/v1/posts`
`status`	sì	`delivered`, `failed` o `skipped`
`external_url`	no	Dove è stato pubblicato
`external_id`	no	L’id del sistema remoto
`error`	no	Perché è fallito, se è successo

Un token può segnalare soltanto i post del proprio sito.

Il payload del post

Una sola struttura canonica, versionata da contract_version.

Campo	Tipo	Note
`id`	string	Stabile. Usalo come chiave di idempotenza
`title`, `slug`, `excerpt`	string	`slug` è quello finale, già deduplicato
`content_html`, `content_md`	string	Il corpo del post, in entrambi i formati
`meta_title`, `meta_description`	string	Metadati SEO
`primary_keyword`, `keywords`, `category`, `tags`	string / array	Tassonomia
`canonical_url`	string	Canonical, se impostato
`schema_json_ld`	object	Già analizzato, mai una stringa JSON
`featured_image_url`	string	Immagine già ospitata, pronta all’uso
`audio_url`	string	Narrazione, se il post ce l’ha
`audio_duration_seconds`, `audio_voice`	number / string	Dettagli della narrazione
`status`	string	`published` o `draft`
`author`, `author_title`, `author_url`	string	Firma dell’autore
`created_at`, `published_at`	ISO 8601	Timestamp

Ogni chiave è sempre presente. Un valore non applicabile viene restituito come null — non viene mai omesso. Un post senza narrazione ha semplicemente audio_url: null; è il caso normale, non un errore. Progetta l’integrazione in modo che si aspetti valori null anziché chiavi mancanti.

Il contratto è solo additivo. I campi non vengono mai rinominati, non cambiano tipo e non spariscono, perché le integrazioni già in uso continuano a chiedere la versione 1 all’infinito. Una modifica incompatibile uscirebbe come nuova versione, servita accanto a questa.

Errori

Gli errori restituiscono lo stato HTTP corrispondente e un corpo JSON con un messaggio leggibile.

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

Stato	Significato
`400`	Campo obbligatorio mancante o non valido
`401`	Token assente, sconosciuto o revocato
`404`	Il post non appartiene a questa connessione

Integrazioni già pronte

Non devi scrivere codice. La stessa API è già pronta per:

WordPress — il plugin ufficiale Get RankBloom. Ti colleghi con un clic, senza token da incollare.
Make — un’app dedicata con Watch Posts come trigger e Mark Post as Published come azione.
Zapier — New Post come trigger e Mark Post as Published come azione.

Assistenza

Domande sull’API o qualcosa che non si comporta come documentato: scrivi a support@getrankbloom.com.