Eigene Anbindung über die Schnittstelle

Die Schnittstelle /api/ingest nimmt Zugriffe von außen entgegen. Der Cloudflare Worker von Agent Franz benutzt sie. Sie können sie auch aus einem eigenen System ansprechen, etwa aus einem Proxy oder einem Dienst, der Zugriffe ohnehin sammelt. Diese Seite richtet sich an Entwickler.

Voraussetzungen

• Ein API-Schlüssel des Arbeitsbereichs. Erzeugen darf ihn nur die Rolle Admin. Den Weg dorthin zeigt Schritt 2 der Cloudflare-Einrichtung mit der Schaltfläche API-Schlüssel erzeugen. Der Schlüssel erscheint genau einmal; kopieren Sie ihn sofort. Mehr dazu unter API-Schlüssel.
• Ein System, das Zugriffe mit Zeitpunkt, IP-Adresse, Kennung des Programms (User-Agent), Pfad, Methode und Statuscode kennt.

Der Schlüssel gehört zu genau einem Arbeitsbereich. Wer ihn hat, kann Daten in diesen Arbeitsbereich schicken. Geben Sie ihn nicht weiter und legen Sie ihn nicht in öffentlich lesbaren Code.

Anfrage

Die Anfrage geht per POST an den Pfad /api/ingest der Adresse https://app.agentfranz.ai. Im Kopf stehen Authorization: Bearer <IHR-API-SCHLÜSSEL> und Content-Type: application/json.

Der Rumpf ist ein JSON-Objekt der Form {"batchId": "…", "events": […]}. Jeder Eintrag in events ist ein Zugriff mit sechs Feldern, hier mit Beispielwerten:

• "timestamp": "2026-10-03T08:15:00Z"
• "ipAddress": "192.0.2.10"
• "userAgent": "Mozilla/5.0 (compatible; GPTBot/1.2)"
• "url": "/produkte/fraesmaschinen"
• "method": "GET"
• "statusCode": 200

Dabei gilt:

• batchId ist eine UUID, die Sie je Stapel neu erzeugen.
• events enthält höchstens 50 Zugriffe. Mehr Zugriffe verteilen Sie auf mehrere Anfragen.
• timestamp ist ein Zeitpunkt im Format ISO 8601 in UTC mit Z am Ende, etwa 2026-10-03T08:15:00Z. Eine Angabe mit Versatz wie +02:00 oder ganz ohne Zeitzone lehnt die Schnittstelle mit validation_failed ab. Er darf höchstens 24 Stunden zurückliegen und höchstens eine Minute in der Zukunft liegen. Ältere Zugriffe nimmt die Schnittstelle nicht an; dafür ist das Hochladen einer Logdatei da.
• ipAddress hat höchstens 45 Zeichen, userAgent und url je höchstens 2048, method höchstens 16. statusCode ist eine ganze Zahl von 100 bis 599.
• Einen Abfrageteil der Adresse (alles ab ?) entfernt Agent Franz vor dem Speichern.
• Das Feld client ist für die Integrationen von Agent Franz gedacht. Für eine eigene Anbindung lassen Sie es weg.
• Das Feld clientVersion nennt die Version der Integration, etwa "0.3.0" beim Cloudflare Worker. Für eine eigene Anbindung lassen Sie es weg.
• Der ganze Rumpf darf höchstens 2 MiB groß sein.

Antworten

• 201 mit {"data":{"accepted":1}}: Der Stapel ist angenommen; accepted nennt die Zahl der Zugriffe.
• 200 mit {"data":{"accepted":0}}: Diesen Stapel hat Agent Franz schon. Schickt Ihr System dieselbe batchId noch einmal, etwa nach einem Abbruch, zählt nichts doppelt.
• 400 mit dem Code validation_failed: Der Rumpf ist kein gültiges JSON oder passt nicht zum Aufbau oben.
• 400 mit dem Code timestamp_out_of_range: Mindestens ein Zeitpunkt liegt außerhalb des erlaubten Fensters. Prüfen Sie die Uhr Ihres Systems und die Zeitzone.
• 401 mit dem Code unauthenticated: Der Kopf Authorization fehlt, ist falsch aufgebaut oder der Schlüssel gilt nicht. Ob der Schlüssel fehlt oder falsch ist, sagt die Antwort absichtlich nicht.
• 410 mit dem Code workspace_deleted: Der Arbeitsbereich liegt im Papierkorb und nimmt keine Daten mehr an.
• 413 mit dem Code payload_too_large: Der Rumpf ist größer als 2 MiB.
• 429 mit dem Code rate_limit_exceeded: Mehr als 600 Lieferungen oder mehr als 5.000 Ereignisse je Minute mit demselben Schlüssel. Ein wiederholtes Paket mit derselben batchId zählt dabei nicht noch einmal. Der Kopf Retry-After nennt die Sekunden bis zum nächsten Versuch.

Fehler kommen immer in derselben Form, zum Beispiel ohne Schlüssel: {"error": {"code": "unauthenticated", "message": "Not authenticated"}}.

So sehen Sie, dass es klappt

Ein Stapel mit dem Status 201 ist gespeichert. Die Zugriffe erscheinen danach auf der Seite Überblick unter Traffic. Antwortet die Schnittstelle dauerhaft mit 401, prüfen Sie zuerst den Schlüssel und das Leerzeichen nach Bearer.

Hinweise für den Betrieb

• Wiederholen Sie einen Stapel nach einem Netzfehler oder einer Antwort 429 mit derselben batchId. Einen Stapel mit der Antwort 400 unverändert zu wiederholen hilft nicht.
• Laufen neben Ihrer Anbindung noch andere Wege für dieselbe Website, zählen Zugriffe doppelt; siehe Logs anbinden.
• Wie Agent Franz mit IP-Adressen und anderen Angaben umgeht, steht in der Datenschutzerklärung.