Tracking
DocsAuthenticates the same publishable key every other public route does, but
accepts it two ways: the X-Sorai-Key header (a fetch() call from
sorai-js), or the request body's public_key field, because
navigator.sendBeacon (what the runtime uses so an event survives
the page unloading) cannot set headers. Both paths resolve through
the identical key lookup, so a beacon-delivered event is authenticated
exactly the way a header-delivered one is.
The event is queued and stored in batches within about a second, which is why it answers 202 rather than 201 or 200; there is nothing yet to return a representation of.
event_id should be the deterministic id
(PageView={session}-{page}-pv, ViewContent={session}-{product}-vc,
InitiateCheckout={order}-ic, Purchase={order_number}-purchase), so
the server-built Conversion API event this same id produces later
dedups against this one on the ad platform's side.
application/jsonevent_id*stringDeterministic id; the dedup key against a redelivered beacon and against this event's server-built Conversion API counterpart.
name*stringPageView, ViewContent, InitiateCheckout, AddPaymentInfo, Purchase, or a custom name passed to Sorai.track.
session_id?stringpage_id?stringuuidproduct_id?stringuuidorder_id?stringuuidcurrency?string3 <= length <= 3attribution?utm_*, fbclid→_fbc, _fbp, ttclid, _ttp, referrer, landing page.
props?Whatever Sorai.track(name, props) was called with.
ts?stringWhen the event happened, client-side. Defaults to the server's receipt time.
date-timepublic_key?stringThe publishable key, for a sendBeacon call that could not set the X-Sorai-Key header. Ignored if the header is present.
store_id?stringRequired when the key is org-scoped rather than store-scoped; must match the key's store otherwise.
uuidpreview?booleanTrue for an event built inside the console builder's draft preview. The server rejects it with 422 rather than counting it; the storefront runtime never sends one, so this only fires against a client that skipped its own guard.
Accepted; the event is buffered for the flush.
application/jsonstatus*"accepted""accepted"curl -X POST 'https://api.sorai.ai/v1/public/events' \ -H 'Content-Type: application/json' \ -d '{ "event_id": "string", "name": "string"}'{ "status": "accepted"}