API Reference

Both SDKs talk to this endpoint under the hood. Use it directly only if you're integrating from a platform neither SDK covers — otherwise prefer the JavaScript or Flutter SDK.

Ingest events

POST /api/v1/event

Body: a batch of one or more events.

{
  "events": [
    {
      "sid":  "YOUR_SITE_ID",     // required — site_id from Integration Hub
      "uid":  "HASHED_USER_ID",   // required — SHA-256 hash, never a raw id
      "p":    "/checkout",        // required — URL path
      "t":    "pageview",         // optional — event type, defaults to "pageview"
      "ref":  "https://google.com", // optional — referrer
      "utm":  { "source": "newsletter" }, // optional — UTM parameters
      "meta": { "plan": "pro" }           // optional — custom event properties
    }
  ]
}

Field	Required	Notes
`sid`	Yes	Site ID from the dashboard's Integration Hub.
`uid`	Yes	SHA-256 hash of the visitor/user id. Both SDKs compute this client-side — never send a raw user id, email, or name.
`p`	Yes	URL path or screen name.
`t`	No	Event type, e.g. `pageview`, `signup_completed`.
`ref`	No	Referrer URL.
`utm`	No	UTM campaign parameters, as a flat object.
`meta`	No	Non-identifying custom event properties.

Authentication

Web requests are authenticated by Origin — the domain making the request must match what was registered for that Site ID in the dashboard (localhost is always allowed outside production).

Non-web requests (mobile/desktop) include the app's Secret Key, issued alongside the Site ID for non-web platforms.

Rate limits & resilience

The ingestion endpoint is rate-limited per site. Both SDKs batch events client-side (flushing periodically or on a size threshold) and persist unsent events locally, so transient network failures or rate-limit responses don't lose data — the client-side batching in the SDKs is the intended usage pattern, not per-event calls.