REST-API

Die CrunchJunkie REST-API bietet programmatischen, nur lesenden Zugriff auf dieselben Daten wie die App und der MCP-Connector — deine Kunden, Berichte und deren Live-Daten sowie KI-Sichtbarkeits-Kennzahlen — über einfaches HTTPS mit JSON-Antworten. Sie ist für Server, Cronjobs, Data-Warehouses und No-Code-Tools wie Zapier oder Make gedacht: überall dort, wo du deine CrunchJunkie-Zahlen brauchst, ohne dass jemand durchs Dashboard klickt. Zwei Dinge sind bewusst so gebaut. Sie ist nur lesend: jeder v1-Endpunkt liest, keiner schreibt — ein geleakter Schlüssel kann also nie etwas ändern, löschen oder Budget ausgeben. Und sie ist team-gebunden: ein Schlüssel gehört zu genau einem Workspace und gibt nur dessen Daten zurück. Verfügbar in den kostenpflichtigen Tarifen (Pro, Agency, Scale), genau wie der MCP-Connector.

Öffne Einstellungen → API. Nur Inhaber oder Admins eines Workspace können Schlüssel erstellen oder widerrufen — ein Schlüssel kann den gesamten Workspace lesen, das ist also keine Mitglieder-Aktion. Gib dem Schlüssel einen Namen (z. B. „Zapier Produktion“) und klicke auf Erstellen. Der vollständige Schlüssel — er sieht aus wie cj_live_ab12cd34.xxxx… — wird genau einmal angezeigt. Kopiere ihn und bewahre ihn sicher auf (Passwort-Manager, das Zugangsdaten-Feld deines Tools); wir behalten nur einen Hash und können ihn dir nicht erneut zeigen. Verlierst du ihn, widerrufe ihn und erstelle einen neuen. Widerrufen wirkt sofort: klicke bei einem Schlüssel auf Widerrufen, und jede Integration, die ihn nutzt, funktioniert ab der nächsten Anfrage nicht mehr. Schlüssel laufen nicht von selbst ab, außer du setzt ein Ablaufdatum.

Die Basis-URL ist https://app.crunchjunkie.io/api/v1. Sende deinen Schlüssel als Bearer-Token im Authorization-Header: curl -H "Authorization: Bearer cj_live_ab12cd34.xxxx…" https://app.crunchjunkie.io/api/v1/clients Jede Antwort ist JSON. Erfolg sieht so aus: { "data": … , "meta": { … } }; ein Fehler so: { "error": { "code": "…", "message": "…" } } mit dem passenden HTTP-Status (401 nicht authentifiziert, 403 falscher Scope oder Tarif, 404 nicht gefunden, 429 Rate-Limit, 500 Serverfehler).

v1 ist nur lesend und spiegelt die MCP-Lese-Tools, die Zahlen stimmen also exakt mit der App überein: • GET /api/v1/clients — deine Kunden, ihre verbundenen Anbieter und Berichtsanzahl. • GET /api/v1/reports?clientId=… — deine Berichte (IDs für die Aufrufe unten). • GET /api/v1/reports/{id} — die Definition eines Berichts (Widgets, Zeitraum-Konfiguration). • GET /api/v1/reports/{id}/data?datePreset=…&comparePreset=… — die live zusammengestellten Daten des Berichts (KPIs, Charts, Tabellen). • GET /api/v1/ai-visibility/projects?clientId=… — deine KI-Sichtbarkeits-Projekte. • GET /api/v1/ai-visibility/projects/{id}/metrics?model=…&dateFrom=…&dateTo=… — Snapshot-Kennzahlen (Sichtbarkeit, Share of Voice, Sentiment, durchschnittliche Position, Erwähnungen). Die maschinenlesbare OpenAPI-3.1-Spezifikation liegt unter https://app.crunchjunkie.io/api/v1/openapi.json — importiere sie in Postman, Insomnia oder deinen Codegen.

Jeder Schlüssel hat ein Token-Bucket-Rate-Limit; überschreitest du es, bekommst du einen 429 mit einem Retry-After-Header, der dir sagt, wie viele Sekunden du warten musst. Große Sammlungen geben die neuesten Zeilen mit meta.total und einem meta.truncated-Flag zurück, damit eine begrenzte Seite nie als vollständige Menge ausgegeben wird — grenze nach Datum oder Modell ein, um ältere Daten zu erreichen. Ein Genauigkeitshinweis, der zählt, wenn du eigene Aggregate berechnest: KI-Sichtbarkeits-Kennzahlen folgen dem Metrik-Vertrag — poole eine Rate, indem du die Zähler und die Läufe summierst und EINMAL teilst (Σ visibilityCount ÷ Σ totalRuns), nie durch Mitteln von Prozentwerten pro Zeile, und halte jeden Markt (Locale) als eigene Population. Die App macht das für dich; mach es nachgelagert genauso, und deine Zahlen stimmen mit unseren überein.