// 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. Im Pro-Abo enthalten: vorhandene Messdaten, Verlauf und To-dos als JSON für eigene Berichte und interne Tools.

Der Aufruf

Ein einziger Endpunkt, nur Lesezugriff auf die eigene Firma. Dafür erhalten Sie einen separaten API-Schlüssel – nicht den Dashboard-Schlüssel.

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

Den Schlüssel ausschließlich im Authorization-Header senden, niemals in der URL oder im öffentlichen Browser-Code. Schlüssel vertraulich behandeln.

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
todos	Vorhandene Maßnahmen, Status und Fundstellen; keine Änderung über die API

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. Der API-Schlüssel kann unabhängig vom Dashboard widerrufen oder ersetzt werden und läuft spätestens zum bei Ausstellung festgelegten Ende des bezahlten Pro-Zeitraums ab.
Nur Lesen. Über die Schnittstelle lässt sich nichts ändern und nichts anlegen.
Keine zusätzlichen KI-Messungen. API-Abrufe liefern bereits gespeicherte Ergebnisse.
Weiterverkauf und White-Label-Angebote bedürfen einer separaten Vereinbarung.
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
403	Pro-Zugang nicht mehr aktiv
429	Tageslimit erreicht
502 / 504	Datenbank antwortet nicht, später erneut versuchen

Zugang

Der lesende API-Zugang ist ohne separaten API-Aufpreis im Pro-Abo enthalten. Ihren Schlüssel erhalten und widerrufen Sie über hello@thecited.ai. Für jedes betreute Unternehmen ist dessen eigener berechtigter Zugang nötig. Audit und Start-Paket enthalten keinen API-Zugang.