The events endpoint
This is the reference for the endpoint your application sends events to. POST /api/v1/events/ is the whole write API in Tidings. It accepts a single event object or a batch.
The payload
An event has two required fields and two optional ones:
| Field | Type | Notes |
|---|---|---|
| name | string | What happened — checkout_completed, page_view, … |
| distinct_id | string | Who did it. Any stable identifier: a user id, a device id, an anonymous session id. When someone signs in, alias their anonymous id into their user id so the two halves stay one person. |
| timestamp | ISO 8601 | Optional. When it happened; defaults to arrival time. |
| properties | object | Optional. Arbitrary JSON context — plan, path, country, anything you'll want to filter by later. |
Send a timestamp in the past and events file into history exactly where they belong — backfills need no special treatment.
Responses & errors
| Status | Meaning |
|---|---|
| 202 | Accepted. Body is {"accepted": n} with the number of events stored. |
| 400 | Invalid payload — a missing field, malformed timestamp, or a batch over 500 events. The body names the field. |
| 401 | Missing, unknown, or revoked API key. |
| 429 | Rate limited. Ingestion allows 600 requests per minute per project; a batch counts as one request. |