Presence
Heartbeats that tell the server which clients are open, so people show as online.
Heartbeats that tell the server which clients are open, so people show as online.
Generated from the OpenAPI spec by
npm run docs:api -w api. Do not edit this page — change the decorators inapps/api/src/and regenerate.
Conventions
- Auth — a session on every route: the cookie on web, the bearer token on mobile. See Authentication.
- Errors — every non-2xx response has the body described in Errors.
- Types — a
?after a field name means it is optional;| nullmeans it is present but may be null.
Endpoints
POST /api/v1/presence/heartbeat — Report that this client is open
Send every 60 seconds while signed in, and once straight away on opening. active is whether the person used the client since the previous heartbeat. With no heartbeat for 180 seconds they read as offline; connected but with no active heartbeat for 300 seconds, as away. Generate connectionId once per launch or page load and reuse it.
Body — PresenceHeartbeatDto
Returns 204 → no body
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
POST /api/v1/presence/connections/{connectionId}/close — Report that this client closed
Send as the page or app closes. Only this connection is closed — the person stays online while any other client of theirs keeps reporting in. Skipping it is safe; the connection simply times out.
| Path parameter | Type | Notes |
|---|---|---|
connectionId | string |
Returns 204 → no body
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
POST /api/v1/presence/sign-out — Close every client of this session
Call immediately before signing out, while the session is still valid. Closes all tabs sharing this session; the person’s other devices are unaffected.
Returns 204 → no body
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
Data models
PresenceHeartbeatDto
| Field | Type | Notes |
|---|---|---|
connectionId | string | A random UUID the client generates once per page load and sends with every heartbeat. It is how one tab is told apart from another of the same person. |
active | boolean | Whether the page is visible and saw input since its previous heartbeat. false keeps the person connected without counting as activity — a tab left open in the background makes them Away, not Active. |