Skip to Content
API ReferenceREST API (/v1)

REST API (/v1) Available (v1)

The public REST API lives at the base https://ingest.visz.ai/v1; every endpoint is a /v1/… path (the bare host https://ingest.visz.ai/ serves no document). It is the HTTP ingest surface, that is the same endpoints the tracking snippet calls under the hood. Most people never touch it directly (use the JavaScript API instead), but it is fully documented here for server-side ingestion and custom clients.

Authentication

All /v1/ingest/* routes require your public tracking key (vz_…), preferably in the X-Tracking-Key header. The server also accepts it as a tracking_key field in the JSON body. The key ships in your snippet and is public by design.

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

/v1/health and the public /v1/share/{token} routes need no authentication.

Origin check

If a request sends an Origin or Referer header, its host must match the website’s domain (the domain itself, its www. variant, or a subdomain). A foreign host gets 403 with ORIGIN_NOT_ALLOWED. Requests without these headers at all, for example from your server, are let through.

The API enforces consent at session-start: if consent.state is not "granted", the server answers 202 and creates neither a visitor nor a session. The only thing stored then is a consent log entry as proof of the decision, without a visitor identifier.

Interactive reference

The full, interactive reference below is generated from the OpenAPI 3.1 specification of the ingest API: every endpoint, schema, example, and error code.

Loading API reference …

Rate limits & errors

Each route is rate-limited through Redis, per time window and per tracking key plus anonymized IP or per tracking key plus session. When you exceed the limit you get 429 with the code RATE_LIMITED and a Retry-After header. All errors share one envelope:

{ "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 identifies the request; if you send an X-Request-Id header, the API uses its value. For 429, retry_after gives the wait time in seconds. Validation errors add a details field. The message text is currently in German; branch on code, not on message. Common codes include INVALID_TRACKING_KEY, ORIGIN_NOT_ALLOWED, RATE_LIMITED, and SHARE_NOT_FOUND. The full per-endpoint list lives in the interactive reference above.

Last updated: