Skip to main content

​
Authentication

Every request must carry a bearer token:
A missing or invalid token returns 401. The token is a per-venue shared secret, provisioned during integration.

​
Request body

Send either a single event object, or an array of up to 500 events. A batch is all-or-nothing: if any event in the array is invalid, the whole batch is rejected and nothing is stored.

​
Event envelope

​
string
required
Unique, stable id for the event. Resends MUST carry the same event_id — this is how Pulse de-duplicates.
​
string
required
The play session this event belongs to.
​
string
required
Assigned venue identifier.
​
string
required
Assigned court identifier.
​
string (ISO 8601)
required
Event Occurrence Time — when the event happened, not when it was sent. Pulse orders by this. Must include a timezone offset (e.g. the trailing Z).
​
string
required
One of the event types: BALL_BOUNCE, BALL_HIT, BALL_SPEED, PLAYER_POSITION, PLAYER_IDENTITY.
​
number
required
Detection confidence, 0.0–1.0.
​
string
required
The event source, e.g. your-system.
​
string
required
Protocol version. Currently "1.0".
​
integer
default:"0"
0 for a first (preliminary) emission; a higher revision confirms or corrects it. See preliminary → confirmed.
​
object
required
Type-specific fields — see Event types.

​
Response

A success returns 202 Accepted:
​
integer
Number of events newly stored.
​
integer
Number of events already seen (same session_id + event_id + revision) and safely ignored.
For every other status code — validation, auth, rate limiting, and retryable failures — see Errors & retries.