Skip to Content
API ReferenceOverview

API Reference Available (v1)

visz.ai exposes three public interfaces. Pick the one that fits your task; they cover different layers and you rarely need more than one.

InterfaceWhat it isUse it for
REST API (/v1)The HTTP ingest surface at https://ingest.visz.ai. Authenticated with your public tracking key (X-Tracking-Key).Server-side ingestion and custom integrations, that is anything the snippet sends under the hood.
JavaScript APIThe global visz(...) command queue exposed by the tracking snippet.Custom events, identify, and consent control from your own page code. For most integrations this is the right choice.
WebhooksSigned, outbound HTTP calls your workspace can subscribe to.Reacting in your own systems to notices such as a surge of frustrated sessions, an error during a purchase, or a mention.

Which one do I want?

  • “I just want to track a button click or a purchase.” Use the JavaScript API. You call visz('event', ...) from your page; the snippet handles batching, consent, and PII masking for you. It also works without code: see Custom Events & Tags.
  • “I’m sending data from my backend or a non-browser client.” Use the REST API directly with your tracking key.
  • “I want to be notified when something happens in visz.ai.” Set up a Webhook.

A note on tRPC

visz.ai’s dashboard talks to its backend over an internal tRPC API. That API is not a public contract: it is undocumented, unversioned, and may change at any time. The only public, stable surfaces are the three above: REST /v1, the JavaScript snippet API, and Webhooks.

Authentication at a glance

  • REST /v1 ingest routes are authenticated with your public tracking key (vz_…) via the X-Tracking-Key header. It is public by design; it ships in your tracking snippet.
  • /v1/health and /v1/share/{token} need no authentication.
  • Webhooks are authenticated the other way around: you verify with your own signing secret that a request really came from visz.ai by checking the X-Visz-Signature HMAC.

Last updated: