API

Review-Sources-API

Review-Quellen (Google, Trustpilot, etc.) registrieren, Reviews pullen, Trends auslesen.

Review-Sources sind externe Bewertungs-Plattformen (Google Business Profile, Trustpilot, Yelp, ProvenExpert, Trusted Shops, …), die Rankion in regelmäßigen Pulls abklappert und konsolidiert. Über die API verwaltest du Sources, rotierst Auth-Keys und empfängst optional Echtzeit-Updates per Webhook — der einzige outbound-fähige Webhook-Endpoint der gesamten Rankion-API.

Modul-Kontext: Review Sources · siehe auch Webhooks.

Sources verwalten

Method	Endpoint	Beschreibung
GET	`/v1/review-sources`	Alle aktiven Sources (Plattform, Status, Last-Pull)
GET	`/v1/review-sources/{id}`	Detail inkl. aktueller Reviews-Liste
DELETE	`/v1/review-sources/{id}`	Source entfernen

curl "$BASE/review-sources" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, platform, source_url, status, avg_rating, total_reviews, last_pull_at}'

Auth-Steuerung

Pro Source existiert ein Auth-Key (für key-basierte Plattformen) bzw. eine OAuth-Connection (für Google).

Method	Endpoint	Beschreibung
POST	`/v1/review-sources/{id}/rotate-key`	Auth-Key rotieren (alter Key sofort ungültig)
POST	`/v1/review-sources/{id}/disconnect`	Source pausieren ohne zu löschen
POST	`/v1/review-sources/{id}/reconnect`	Pausierte Source reaktivieren

curl -X POST "$BASE/review-sources/4/rotate-key" \
  -H "Authorization: Bearer $TOKEN"

Response liefert den neuen Key genau einmal — danach nur noch maskiert (xxxx-…-1234). Speichere ihn sofort in deiner Konfig.

Source-Onboarding

Neue Sources werden über zwei Wege angelegt: aktive Webhook-Registrierung (für Plattformen mit Push-Support) oder Waitlist-Eintrag (für noch nicht freigeschaltete Plattformen).

Method	Endpoint	Beschreibung
POST	`/v1/review-sources/webhook`	Neue Source mit Webhook-Setup registrieren
POST	`/v1/review-sources/waitlist`	Anfrage für eine noch nicht unterstützte Plattform

curl -X POST "$BASE/review-sources/webhook" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"platform": "trustpilot", "source_url": "https://trustpilot.com/review/example.com"}'

Public Review-Webhook (inbound)

Externe Plattformen oder Zapier/Make können Reviews direkt an Rankion pushen — das ist der einzige öffentliche, key-authentifizierte Endpoint der API.

Method	Endpoint	Auth	Beschreibung
POST	`/v1/webhooks/reviews/{source}`	`X-Rankion-Key: <source_key>`	Eine Review als JSON pushen

{source} ist der slug einer Source aus GET /review-sources (z.B. trustpilot-example-com). Auth läuft nicht über Authorization: Bearer, sondern über den source-spezifischen Key aus rotate-key. Damit kannst du den Webhook-URL safe an Drittsysteme geben, ohne den Master-Token zu teilen.

curl -X POST "https://rankion.ai/api/v1/webhooks/reviews/trustpilot-example-com" \
  -H "X-Rankion-Key: $SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "tp-987654",
    "rating": 5,
    "title": "Top Service",
    "body": "Schnelle Antwort, alles glatt.",
    "author": "Anna M.",
    "submitted_at": "2026-04-30T11:22:33Z",
    "url": "https://trustpilot.com/reviews/987654"
  }'

Response 200:

{"received": true, "review_id": 4521, "duplicate": false}

Bei duplicate: true wurde die Review per external_id deduped — kein neuer Insert, kein Fehler.

Hinweise

Webhook-Key ≠ API-Token. Der X-Rankion-Key autorisiert nur Pushes an diese eine Source — er kann nichts lesen, nichts ändern, nichts an anderer Stelle aufrufen. Kompromittierung beschränkt sich auf gefälschte Reviews für eine Source.
Rotate sofort nach Compromise. POST /rotate-key invalidiert den alten Key atomar — Inflight-Requests mit altem Key bekommen 401.
Disconnect statt DELETE, wenn du nur pausieren willst. DELETE entfernt auch alle gepullten Reviews aus der DB (kaskadiert).
Cron-Pulls laufen automatisch alle 6 h pro aktiver Source. Manueller Re-Pull ist (Stand 2026-05) nur über die UI möglich.
Google-Reviews laufen über OAuth, nicht über Source-Keys — siehe Google-Integrations-API.

Verwandt: Google Integrations · Webhooks · Review Sources.

Letzte Aktualisierung: 1. Mai 2026