Sessions

Session rows feed the /admin/sessions analytics endpoints. All mutations are scoped by app_user_id so a session id leaked via logs can't be ended or bumped by another user.

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

Endpoints

Method	Path	Description
POST	`/client/sessions/start`	Open a session row.
POST	`/client/sessions/end`	Close a session with `duration_seconds`.
POST	`/client/sessions/heartbeat`	Bump `duration_seconds` while the session is open.

POST /client/sessions/start

Request (`StartSessionInput`)

Field	Type	Required
`session_id`	string	yes
`platform`	string	no
`app_version`	string	no
`device_model`	string	no
`metadata`	object	no

Response 201

{
  "data": {
    "id": "…",
    "session_id": "…",
    "started_at": "…",
    "platform": "ios",
    "app_version": "1.0.0"
  }
}

Errors

500 CREATE_FAILED.

Try it:

POST/client/sessions/start

client auth

curl -X POST 'https://api.amba.dev/client/sessions/start'

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

Curl:

curl -X POST '${BASE_URL}/client/sessions/start' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/sessions/end

Request (`EndSessionInput`)

Field	Type	Required
`session_id`	string	yes

Computes duration_seconds from the stored started_at and stamps ended_at = NOW().

Response 200

{ "data": { "id": "…", "session_id": "…", "ended_at": "…", "duration_seconds": 300 } }

Errors

404 UPDATE_FAILED — session not found for this user.

Try it:

POST/client/sessions/end

client auth

curl -X POST 'https://api.amba.dev/client/sessions/end'

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

Curl:

curl -X POST '${BASE_URL}/client/sessions/end' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/sessions/heartbeat

Request

Field	Type	Required
`session_id`	string	yes

Updates duration_seconds to the delta since started_at. Does not close the session.

Response 200

Updated row.

Errors

404 UPDATE_FAILED.

Try it:

POST/client/sessions/heartbeat

client auth

curl -X POST 'https://api.amba.dev/client/sessions/heartbeat'

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

Curl:

curl -X POST '${BASE_URL}/client/sessions/heartbeat' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

On this page