Events

Every Amba.track() call sends a POST here. Events drive streak qualification and XP award evaluation server-side; the SDK additionally forwards events to App Machina analytics client-side, so this endpoint never double-writes to analytics.

Source: apps/api/src/routes/client/events.ts.

Endpoints

Method	Path	Description
POST	`/client/events`	Track one or many events.

POST /client/events

Accepts either a single event or a { events: […] } batch.

Request — single event

{
  "event": "workout_completed",
  "properties": { "duration_minutes": 30 },
  "timestamp": "2026-04-24T12:00:00Z"
}

Request — batch

{ "events": [{ "event": "…" }, { "event": "…" }] }

Per-event fields (TrackEventInput):

Field	Type	Required	Description
`event`	string	yes	Event name.
`properties`	object	no	Arbitrary JSONB properties.
`timestamp`	ISO-8601	no	Defaults to `now()`.

Limits

Max batch size: 500 events per request. Exceeding returns 413 BATCH_TOO_LARGE.
Streak qualification is checked asynchronously after the write — it cannot fail the request.
last_seen_at on app_users is updated fire-and-forget.

Response 200

{ "data": { "tracked": 30 } }

Empty batch returns { "data": { "tracked": 0 } }.

Errors

413 BATCH_TOO_LARGE — batch exceeds 500 events.
500 TRACK_FAILED.

Try it:

POST/client/events

client auth

curl -X POST 'https://api.amba.dev/client/events' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "workout_completed",
  "properties": {
    "duration_minutes": 30
  },
  "timestamp": "2026-04-24T12:00:00Z"
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/events' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"event":"workout_completed","properties":{"duration_minutes":30},"timestamp":"2026-04-24T12:00:00Z"}'