> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playpicklx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoint reference

> POST /v1/events — the single ingestion endpoint.

```
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`](/errors). 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

<ParamField body="event_id" type="string" required>
  Unique, stable id for the event. Resends MUST carry the same `event_id` — this is how
  Pulse de-duplicates.
</ParamField>

<ParamField body="session_id" type="string" required>
  The play session this event belongs to.
</ParamField>

<ParamField body="venue_id" type="string" required>
  Assigned venue identifier.
</ParamField>

<ParamField body="court_id" type="string" required>
  Assigned court identifier.
</ParamField>

<ParamField body="eot" type="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`).
</ParamField>

<ParamField body="type" type="string" required>
  One of the [event types](/event-types): `BALL_BOUNCE`, `BALL_HIT`, `BALL_SPEED`,
  `PLAYER_POSITION`, `PLAYER_IDENTITY`.
</ParamField>

<ParamField body="confidence" type="number" required>
  Detection confidence, `0.0`–`1.0`.
</ParamField>

<ParamField body="source" type="string" required>
  The event source, e.g. `your-system`.
</ParamField>

<ParamField body="schema_version" type="string" required>
  Protocol version. Currently `"1.0"`.
</ParamField>

<ParamField body="revision" type="integer" default="0">
  `0` for a first (preliminary) emission; a higher revision confirms or corrects it. See
  [preliminary → confirmed](/delivery-semantics).
</ParamField>

<ParamField body="payload" type="object" required>
  Type-specific fields — see [Event types](/event-types).
</ParamField>

## Response

A success returns **`202 Accepted`**:

<ResponseField name="accepted" type="integer">
  Number of events newly stored.
</ResponseField>

<ResponseField name="duplicates" type="integer">
  Number of events already seen (same `session_id` + `event_id` + `revision`) and safely
  ignored.
</ResponseField>

```json theme={null}
{ "accepted": 3, "duplicates": 1 }
```

For every other status code — validation, auth, rate limiting, and retryable failures —
see [Errors & retries](/errors).