Events API

Collection routes

Method	Path	Authentication
POST	/api/v1/sdk/events	Collection key, events:write
POST	/api/v1/sdk/events/batch	Collection key, events:write

Send the key as a Bearer token without X-Project-Id. A JWT session is not a substitute for the SDK collection-key requirement.

Single event

{
  "eventId": "47e62de4-dda7-431b-a831-f8494d0c0f4a",
  "eventName": "dashboard_viewed",
  "anonymousId": "example-visitor",
  "properties": { "section": "overview" }
}

Generate a fresh eventId for each new occurrence. Keep the same ID when retrying that occurrence: deduplication is scoped to the project. eventName and eventId are required. Use a stable pseudonymous anonymousId; do not encode raw personal information in it. timestamp can be an ISO 8601 instant. Do not invent a type field to represent the event name.

Batch

{
  "events": [
    { "eventId": "e20161e7-4f60-4fa9-9352-1002cc7538ca", "eventName": "page_viewed", "anonymousId": "example-visitor" },
    { "eventId": "c92eb43a-e3d0-4593-b277-762452460122", "eventName": "button_clicked", "anonymousId": "example-visitor" }
  ]
}

A batch contains 1 to 100 events. The response is 200 OK and reports accepted, rejected, duplicates and discardedConsent. Check these counters; HTTP success alone does not mean every event was stored.

Consent rules remain authoritative. Do not replay events collected before consent. Revocation can discard queued events but cannot undo a request already admitted for delivery. Use the appropriate privacy workflow for stored data.

Campaign attribution is canonical in context.campaign with source, medium, name, term and content. Empty or unavailable values should be omitted rather than fabricated. See Web SDK.