Events and identity

POST /v1/events accepts one event or up to 100 (events: [...], 32 KB each). The client supplies id (unique per environment forever), name, customer_id or anonymous_id, occurred_at (at most 24 h in the future; older than 30 days is flagged late) and properties.

• async (default): 202 with the event id; poll GET /events/{id} for status.
• sync: 200 with effects and trace; falls back to 202 fallback: true if evaluation cannot finish in time. Sync is for secret keys only.
• batch: 207 with one result per item (evaluated, accepted, duplicate, rejected).

A duplicate id returns the original result; a duplicate id with a different payload is 409 event_id_conflict.

Trust contract

Publishable keys (opk_…) may send only events whose definition has client_allowed: true, are forced async, and identify customers by anonymous_id or by a customer_token minted server side with POST /customers/{id}/client_token. Valuable events (order.paid) stay server-only and return 403 event_requires_secret_key from a publishable key.

Identity

Customers are keyed by your external_id. Anonymous visitors become anon:<id> customers; POST /customers/{id}/aliases links the alias to the known customer and re-points history (balances are not merged in V1). An alias already linked elsewhere is 409 alias_conflict. Deleting a customer redacts attributes and event properties, removes aliases and keeps ledger rows for liability (ADR 0010).