Presence and state API

3 endpoints.

GET /v1/presence#

1
2

curl "$BASE/v1/presence?ids=p1,p2,p3" \
  -H "Authorization: Bearer $TOKEN"

1
2
3
4
5
6
7

{
  "data": {
    "p1": "online",
    "p2": "idle",
    "p3": "offline"
  }
}

Use this for member lists and search results. Don't poll — subscribe to the presence WebSocket event for live updates and use this for the initial snapshot.

States: online, idle, busy, appear_offline, offline.

GET /v1/rooms/{room_id}/state#

A single denormalised snapshot of everything client-side state typically needs:

{
  "data": {
    "room": { /* room metadata */ },
    "members": [ /* members with their per-room state */ ],
    "engagement": { /* mode + per-AI overrides */ },
    "plan": null,         // or full plan if one is active
    "active_sidekicks": [ /* live sidekicks */ ],
    "active_call": null,  // or call state
    "unread_count": 7,
    "last_read_event_id": "evt-…",
    "muted_until": null,
    "snoozed_event_ids": []
  }
}

Faster than 7 parallel requests on first room-open. Internal use is the client mounting a fresh room view; you can use it too.

PUT /v1/typing#

1
2
3

curl -X PUT "$BASE/v1/typing" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"room_id": "room-…", "typing": true}'

Sets your typing indicator. Auto-clears after 4 seconds of no re-publish. Use typing: false to clear early.

Fan out to other room members via the typing WebSocket event.