Publish-API

RankBloom schreibt SEO-Blogartikel für die Websites, die Sie damit verbinden. Über die Publish-API verlässt der fertige Inhalt RankBloom und landet dort, wo Sie ihn haben wollen — auf einer WordPress-Website, in einem CMS, auf einer Automatisierungsplattform oder in Ihrem eigenen Code.

Es ist dieselbe API, die hinter dem offiziellen WordPress-Plugin und den Integrationen für Zapier und Make steckt.

Basis-URL

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

Authentifizierung

Jede Anfrage enthält ein Verbindungs-Token. Erstellen Sie eines in RankBloom unter Verbindungen: Wählen Sie die Website und die Plattform und klicken Sie auf Verbindung erstellen. Das Token wird nur einmal angezeigt und ausschließlich als Hash gespeichert — bewahren Sie es also gleich auf.

Ein Token gilt für genau eine Website. Senden Sie es in einem dieser Header:

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

Drei Varianten werden akzeptiert: Shared- und Managed-Hoster entfernen regelmäßig den Header Authorization, und manche Automatisierungsplattformen senden standardmäßig den Header X-API-KEY mit.

Schreiben Sie das Token niemals in einen Query-String. Es landet sonst in Access-Logs und bei jedem Proxy auf dem Weg. Die API liest es dort ohnehin nicht aus.

Das Widerrufen einer Verbindung wirkt sofort. Widerrufene und unbekannte Token liefern dieselbe Antwort, damit niemand über den Unterschied gültige Token erraten kann.

Endpunkte

GET /v1/ping

Prüft ein Token und meldet, woran es gebunden ist. Nutzen Sie den Endpunkt als Verbindungstest.

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 ist ein flacher, gut lesbarer Name für die Verbindung. Automatisierungsplattformen beschriften damit das verbundene Konto.

GET /v1/posts

Aktuelle Beiträge der verbundenen Website, neueste zuerst. Nur lesend — der Aufruf ändert nichts und lässt sich gefahrlos getaktet abfragen.

Parameter	Typ	Standard	Hinweise
`limit`	integer	25	Maximal 100
`offset`	integer	0	So viele Beiträge überspringen
`since`	ISO 8601	—	Nur Beiträge, die ab diesem Zeitpunkt erstellt wurden

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

Paginierung. Erhöhen Sie offset um limit und arbeiten Sie sich so durch das Archiv zurück. Es gibt keine Gesamtzahl: Eine Seite mit weniger Einträgen als limit bedeutet, dass Sie das Ende erreicht haben. Die Ergebnisse sind nach Erstellungszeit und dann nach ID sortiert, sodass die Paginierung auch dann stabil bleibt, wenn zwei Beiträge denselben Zeitstempel tragen.

POST /v1/status

Melden Sie RankBloom, was mit einem Beitrag passiert ist. Erst das macht aus „wir haben ihn übergeben“ ein „er ist live“ — und der Beitrag wird nicht erneut angeboten.

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

Feld	Pflicht	Hinweise
`post_id`	ja	Die `id` aus `/v1/posts`
`status`	ja	`delivered`, `failed` oder `skipped`
`external_url`	nein	Wo er live gegangen ist
`external_id`	nein	Die eigene ID des Zielsystems
`error`	nein	Warum es fehlgeschlagen ist, sofern zutreffend

Ein Token darf nur Beiträge melden, die zu seiner eigenen Website gehören.

Payload eines Beitrags

Ein kanonisches Format, versioniert über contract_version.

Feld	Typ	Hinweise
`id`	string	Stabil. Nutzen Sie den Wert als Idempotenz-Schlüssel
`title`, `slug`, `excerpt`	string	`slug` ist der endgültige, bereits eindeutige Slug
`content_html`, `content_md`	string	Der Beitragstext, in beiden Formaten
`meta_title`, `meta_description`	string	SEO-Metadaten
`primary_keyword`, `keywords`, `category`, `tags`	string / array	Taxonomie
`canonical_url`	string	Canonical, sofern gesetzt
`schema_json_ld`	object	Geparst, nie ein JSON-String
`featured_image_url`	string	Gehostetes Bild, sofort nutzbar
`audio_url`	string	Audioversion, sofern der Beitrag eine hat
`audio_duration_seconds`, `audio_voice`	number / string	Details zur Audioversion
`status`	string	`published` oder `draft`
`author`, `author_title`, `author_url`	string	Autorenzeile
`created_at`, `published_at`	ISO 8601	Zeitstempel

Jeder Schlüssel ist immer vorhanden. Ein nicht zutreffender Wert kommt als null zurück — er wird nie weggelassen. Ein Beitrag ohne Audioversion hat einfach audio_url: null; das ist der Normalfall und kein Fehler. Bauen Sie Ihre Integration so, dass sie mit null-Werten rechnet statt mit fehlenden Schlüsseln.

Der API-Vertrag ist rein additiv. Felder werden nie umbenannt, im Typ geändert oder entfernt, denn Integrationen im Produktivbetrieb fragen Version 1 auf unbestimmte Zeit weiter ab. Ein Breaking Change erschiene als neue Version, die parallel zu dieser ausgeliefert wird.

Fehler

Fehler liefern einen passenden HTTP-Status und einen JSON-Body mit einer verständlichen Fehlermeldung.

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

Status	Bedeutung
`400`	Ein Pflichtfeld fehlt oder ist fehlerhaft
`401`	Token fehlt, ist unbekannt oder widerrufen
`404`	Der Beitrag gehört nicht zu dieser Verbindung

Fertige Integrationen

Sie müssen keinen Code schreiben — für diese Plattformen ist die API bereits fertig integriert:

WordPress — das offizielle Plugin „Get RankBloom“. Mit einem Klick verbunden, ohne ein Token einzufügen.
Make — eine eigene App mit Watch Posts als Trigger und Mark Post as Published als Aktion.
Zapier — mit New Post als Trigger und Mark Post as Published als Aktion.

Support

Haben Sie Fragen zur API oder verhält sich etwas anders als dokumentiert? Schreiben Sie an support@getrankbloom.com.