Skip to main content
POST http://<pulse-host>:4000/v1/events

​
Authentication

Every request must carry a bearer token: 
Authorization: Bearer <shared-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

​
event_id
string
required
Unique, stable id for the event. Resends MUST carry the same event_id — this is how Pulse de-duplicates.
​
session_id
string
required
The play session this event belongs to.
​
venue_id
string
required
Assigned venue identifier.
​
court_id
string
required
Assigned court identifier.
​
eot
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).
​
type
string
required
One of the event types: BALL_BOUNCE, BALL_HIT, BALL_SPEED, PLAYER_POSITION, PLAYER_IDENTITY.
​
confidence
number
required
Detection confidence, 0.0–1.0.
​
source
string
required
The event source, e.g. your-system.
​
schema_version
string
required
Protocol version. Currently "1.0".
​
revision
integer
default:"0"
0 for a first (preliminary) emission; a higher revision confirms or corrects it. See preliminary → confirmed.
​
payload
object
required
Type-specific fields — see Event types.

​
Response

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