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.
Consent gate
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.
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: