API overview
The service speaks JSON over HTTPS. The reference in the sidebar is generated from the service's own OpenAPI description and lets you send live requests; these pages say how the endpoints fit together.
| Endpoint | For | Key |
|---|---|---|
POST /v1/batch, POST /v1/page, /v1/track, /v1/identify, /v1/alias, /v1/group, /v1/screen | Tracking calls in the Segment format, from the SDK or any Segment/RudderStack client | any class |
POST /v1/activities | Activities, for senders that speak the catalogue's language | any class; the catalogue says which activities each may send |
GET /v1/config?key=pk_… | What the browser SDK loads with its key: click ids, banner-exempt events, shop domains, owner paths | browser |
Authentication
HTTP Basic with the write key's secret as the user name and an empty password: pk_live_…, sk_live_… or ik_…, never the wk_ key id. A browser key may travel in the body as writeKey on the two ingestion endpoints. See write keys.
Answers
202 Accepted: everything in the request is durably stored. What becomes of each event is decided after the acknowledgement; withdebug: truethe answer says it at once (validation).400,401,403,413,429: the request as a whole was refused and nothing was stored. The body is{ "error": "…", "trace_id": "…" }.503: the raw log could not take the batch. Nothing was stored; retry.
A 429 carries Retry-After in seconds.
Trace ids
Every answer carries X-Trace-Id and trace_id in the body. A request may send a W3C traceparent header (or field, where the header cannot be set) to continue its own trace; the service's spans then join it. Quote the trace id when asking why something was quarantined.
Limits
500 KB per request body; a rate limit per key, with 429 above it. Batches of up to a few hundred activities are the comfortable size.