Skip to Content
API-ReferenzREST-API (/v1)

REST-API (/v1) Verfügbar (v1)

Die öffentliche REST-API liegt unter der Basis https://ingest.visz.ai/v1; alle Endpoints sind /v1/…-Pfade (der nackte Host https://ingest.visz.ai/ liefert kein Dokument). Sie ist die HTTP-Ingest-Oberfläche, also dieselben Endpoints, die das Tracking-Snippet unter der Haube aufruft. Die meisten fassen sie nie direkt an (nimm stattdessen die JavaScript-API); für server-seitige Ingestion und eigene Clients ist sie hier aber vollständig dokumentiert.

Authentifizierung

Alle /v1/ingest/*-Routen brauchen deinen öffentlichen Tracking-Key (vz_…), am besten im X-Tracking-Key-Header. Der Server nimmt ihn ersatzweise auch als Feld tracking_key im JSON-Body an. Der Key steckt in deinem Snippet und ist bewusst öffentlich.

POST /v1/ingest/event-batch HTTP/1.1 Host: ingest.visz.ai Content-Type: application/json X-Tracking-Key: vz_your_key

/v1/health und die öffentlichen /v1/share/{token}-Routen brauchen keine Authentifizierung.

Herkunftsprüfung

Schickt ein Request einen Origin- oder Referer-Header, muss dessen Host zur Domain der Website passen (die Domain selbst, ihre www.-Variante oder eine Subdomain). Ein fremder Host bekommt 403 mit ORIGIN_NOT_ALLOWED. Requests ganz ohne diese Header, etwa von deinem Server, lässt die API durch.

Die API erzwingt Consent beim session-start: Ist consent.state nicht "granted", antwortet der Server mit 202 und legt weder Besucher noch Sitzung an. Gespeichert wird dann nur ein Consent-Protokolleintrag als Nachweis der Entscheidung, ohne Besucherkennung.

Interaktive Referenz

Die vollständige, interaktive Referenz unten wird aus der OpenAPI-3.1-Spezifikation der Ingest-API erzeugt: jeder Endpoint, jedes Schema, jedes Beispiel und jeder Error-Code.

API-Referenz wird geladen …

Rate-Limits & Fehler

Jede Route ist über Redis rate-limitiert, je Zeitfenster und je Tracking-Key plus anonymisierter IP oder je Tracking-Key plus Sitzung. Überschreitest du das Limit, bekommst du 429 mit dem Code RATE_LIMITED und einem Retry-After-Header. Alle Fehler teilen sich eine Hülle:

{ "error": { "code": "INVALID_TRACKING_KEY", "message": "Der Tracking-Schlüssel ist unbekannt oder deaktiviert.", "request_id": "0192f3a4-b5c6-7d8e-9f01-23456789abcd", "retry_after": null } }

request_id ist die Kennung des Requests; schickst du einen X-Request-Id-Header mit, übernimmt die API dessen Wert. retry_after nennt bei 429 die Wartezeit in Sekunden. Bei Validierungsfehlern kommt ein Feld details hinzu. Der Text in message ist auf Deutsch; verzweige über code, nicht über message. Häufige Codes sind INVALID_TRACKING_KEY, ORIGIN_NOT_ALLOWED, RATE_LIMITED und SHARE_NOT_FOUND. Die vollständige Liste je Endpoint steht in der interaktiven Referenz oben.

Zuletzt aktualisiert: