Yavio

API Reference

HTTP API documentation for the Yavio Ingestion API

The Yavio Ingestion API is the HTTP interface used by the server SDK and widget SDK to send analytics events. All endpoints are served by the @yavio/ingest service (default port 3001).

You typically don't need to call these endpoints directly — the SDK handles event batching and delivery automatically. This reference is useful for building custom integrations or debugging.

Authentication

All endpoints (except /health) require a Bearer token in the Authorization header:

  • Server SDK — uses a project API key (yav_...) obtained from the Yavio dashboard
  • Widget SDK — uses a short-lived JWT minted by the server via POST /v1/widget-tokens

Endpoints

POST /v1/events

Submit a batch of analytics events for processing

POST /v1/widget-tokens

Mint a short-lived JWT for widget event ingestion

GET /health

Liveness probe for service health monitoring

Troubleshooting

Diagnose and fix common self-hosting issues

Ingest event batch POST

Receives a batch of analytics events from the server SDK or widget SDK. Events are validated, PII-stripped, and written to ClickHouse.

On this page

AuthenticationEndpoints