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 Tarifen Pro, Agency und Scale. (Der MCP-Connector ist in jedem bezahlten Tarif enthalten.)

Ö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). Berichte unter „Gelöscht“ fehlen darin; mit includeDeleted=true werden sie mit aufgeführt, markiert mit deleted: true. • 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). Eine Voreinstellung wird wie in der App in der Zeitzone des Workspaces aufgelöst, und die Antwort enthält den aufgelösten dateRange. Mit brandFilter=branded oder brandFilter=nonbranded liest du seine Search-Console-Widgets und jedes andere Widget, das Suchanfragen oder Keywords zählt, nur für diese Gruppe. • GET /api/v1/ai-visibility/projects?clientId=… — deine KI-Sichtbarkeits-Projekte. • GET /api/v1/ai-visibility/projects/{id}/metrics?dateFrom=…&dateTo=…&model=…&market=…&source=… — KI-Sichtbarkeit über ganze UTC-Tage (standardmäßig die letzten 30, höchstens 180): jede Marke gepoolt über alle Antworten (Antworten, die sie nennen, ÷ Antworten, mit den Antworten als n und der ±-Fehlerspanne), der Kunde je Engine und die Snapshot-Zeilen dahinter, jede mit Engine-Bezeichnung und Quelle. Sentiment liegt auf 0–100 mit 50 als neutral, Position 1 heißt zuerst genannt; meta.note nennt die Pooling-Regel. In /reports/{id}/data ist prev einer KPI-Metrik der Wert des Vergleichszeitraums. Er ist null, wenn es nichts zum Vergleichen gibt: kein Vergleichszeitraum, keine früheren Daten für diese Metrik, ein Vergleichszeitraum, den die Quelle nicht liefern konnte, oder eine Zahl, die es nur im heutigen Stand gibt (Katalogzahlen, Bewertungszahlen, Follower-Zahlen). Er ist eine Zahl, auch 0, wenn der Vergleichszeitraum gemessen wurde: 0 ist eine echte vorherige 0, von der es keine prozentuale Veränderung gibt. Jedes KPI-Widget trägt prevNull: true; meta.note sagt dasselbe. Der Wert (value) einer KPI ist null, wenn es keine Zahl gibt: Das Lesen ist fehlgeschlagen, oder der Wert lässt sich nicht berechnen (zum Beispiel Kosten pro Conversion bei 0 Conversions). Er steht nie für 0. Ein Search-Console- oder Rank-Tracking-Diagramm in /reports/{id}/data kann googleUpdates enthalten: die Google-Ranking-Updates, die in seinem Zeitraum liefen, aus Googles Search Status Dashboard (Name, Link, Beginn und Ende als Tage nach US-Pazifikzeit, Ende null, solange der Rollout läuft). Sie zeigen nur den Zeitpunkt, keine Ursache, und meta.googleUpdates sagt das, sobald ein Diagramm sie enthält. Ein KI-Sichtbarkeits-Widget zu Quellen oder Zitaten in /reports/{id}/data (und im MCP-Tool get_report_data), das Antworten weggelassen hat, deren URLs aus dem Modellgedächtnis stammen und nicht aus einer Suche, nennt ihre Zahl: memoryExcluded an Tabelle, Donut oder Diagramm, fromMemory an jeder betroffenen KPI-Kennzahl. Diese Antworten stehen weder im Zähler noch im Nenner; die Endpunkte für Zitate und Content-Lücken nennen dieselbe Zahl als answersFromMemoryExcluded. Eine Markentabelle (Brand) der KI-Sichtbarkeit mit Vergleich kann außerdem withinMargin tragen, die Zellen [Zeile, Spalte], deren Veränderung nicht mindestens doppelt so groß ist wie ihre Fehlermarge: Der Bericht zeigt sie grau mit „~“, lies eine solche Veränderung also als unverändert. 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.