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 — the same endpoints the tracking snippet calls under the hood. Most people never touch it directly (use the JavaScript API instead), but it’s fully documented here for server-side ingestion and custom clients.

Authentication

All /v1/ingest/* routes require your public tracking key (vz_…) in the X-Tracking-Key header. 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.

Consent gate. The API enforces consent at session-start: if consent.state is not "granted", the server accepts the request (202) but persists no visitor. Nothing is stored before consent.

Interactive reference

The full, interactive reference below is generated from the same OpenAPI 3.1 spec that powers the API — every endpoint, schema, example, and error code:

Rate limits & errors

Each route is rate-limited with a Redis token bucket (per key/IP or key/session). When you exceed it you get 429 with a SCREAMING_SNAKE error code. All errors share one envelope:

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

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: June 5, 2026