// schnittstelle

Unsere Zahlen in Ihrem Reporting.

Sie betreuen mehrere Kunden und wollen deren KI-Sichtbarkeit nicht in unserem Dashboard zeigen, sondern in Ihrem eigenen Bericht. Dafür gibt es diese Schnittstelle. Ein Aufruf, eine JSON-Antwort, Ihr Logo darüber.

Der Aufruf

Ein einziger Endpunkt, nur Lesezugriff. Der Schlüssel ist derselbe, mit dem Ihr Kunde sein Dashboard öffnet.

curl -H "Authorization: Bearer IHR_SCHLUESSEL" \
  "https://thecited.ai/api/v1/messung?slug=firmenname"

Der Schlüssel darf auch als Parameter &key=… mitkommen. Über den Kopfzeilen-Weg landet er allerdings nicht in Server-Protokollen und Browser-Verläufen, deshalb ist er die bessere Wahl.

Was zurückkommt

Feld	Inhalt
kunde	Name, Website, Branche, Region
messung	Letzte Messung: Score, Note, Nennungen, Läufe, Werte je KI-System
verlauf	Alle bisherigen Messungen mit Datum, für die Kurve im eigenen Bericht
fragen	Jede gemessene Frage mit Nennungen, Läufen und bester Position
wettbewerber	Wer in den Antworten genannt wird, nach Häufigkeit
quellen	Domains, aus denen die Systeme ihre Antworten ziehen
ki_anfragen	Vom Kunden gemeldete Anfragen über KI, je Monat

Grenzen

200 Abrufe pro Kunde und Tag. Darüber antwortet die Schnittstelle mit Status 429. Für ein tägliches Reporting reicht ein Abruf.
Ein Schlüssel je Kunde. Sie halten so viele Schlüssel, wie Sie Kunden betreuen. Kündigt einer, tauschen wir seinen Schlüssel und Ihr Zugriff endet mit ihm.
Nur Lesen. Über die Schnittstelle lässt sich nichts ändern und nichts anlegen.
Version 1. Jede Antwort trägt "version": 1. Wenn sich das Format ändert, steigt die Zahl und die alte Fassung läuft weiter.

Ein Hinweis, den wir jedem Bericht beilegen: KI-Antworten schwanken stark. Eine Einzelmessung beweist wenig, aussagekräftig ist der Verlauf über mehrere Wochen. Wenn Sie unsere Zahlen weiterreichen, geben Sie das bitte mit weiter. Wir nennen zu jeder Zahl das Messdatum, damit das möglich ist.

Fehlercodes

Status	Bedeutung
400	slug oder Schlüssel fehlt
401	Schlüssel passt nicht oder Kunde ist nicht aktiv
429	Tageslimit erreicht
502 / 504	Datenbank antwortet nicht, später erneut versuchen

Zugang

Die Schnittstelle ist für Agenturen und Berater gedacht, die mehrere Kunden betreuen. Schreiben Sie an hello@thecited.ai, dann klären wir Umfang und Konditionen. Für einzelne Firmen genügt das Dashboard.