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 — 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_…) im X-Tracking-Key-Header. 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.

Consent-Gate. Die API erzwingt Consent beim session-start: Ist consent.state nicht "granted", akzeptiert der Server den Request (202), persistiert aber keinen Besucher. Vor der Einwilligung wird nichts gespeichert.

Interaktive Referenz

Die vollständige, interaktive Referenz unten wird aus derselben OpenAPI-3.1-Spec generiert, die auch die API antreibt — jeder Endpoint, jedes Schema, jedes Beispiel und jeder Error-Code:

Rate-Limits & Fehler

Jede Route ist mit einem Redis-Token-Bucket rate-limitiert (pro Key/IP oder Key/Session). Überschreitest du das Limit, bekommst du 429 mit einem SCREAMING_SNAKE-Error-Code. Alle Fehler teilen sich ein Envelope:

{
  "error": {
    "code": "INVALID_TRACKING_KEY",
    "message": "tracking_key is missing or invalid.",
    "request_id": "req_a1b2c3"
  }
}

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: 5. Juni 2026