Users & Presence

List Users

GET /api/v1/users

Returns all users who have connected to your environment.

curl https://pulse.hire.rest/api/v1/users \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "items": [
    {
      "id": "env_abc123:user-1",
      "externalId": "user-1",
      "name": "Alice Chen",
      "avatar": "https://example.com/avatars/alice.jpg",
      "color": "#6366f1",
      "createdAt": "2026-03-10T12:00:00.000Z"
    },
    {
      "id": "env_abc123:user-2",
      "externalId": "user-2",
      "name": "Bob Smith",
      "avatar": null,
      "color": "#f59e0b",
      "createdAt": "2026-03-10T12:30:00.000Z"
    }
  ]
}

externalId is the userId you provided when minting the token. The id field is the internal namespaced ID.

Presence

GET /api/v1/rooms/:roomId/presence

Returns users currently connected to a room via WebSocket.

curl https://pulse.hire.rest/api/v1/rooms/dashboard/presence \
  -H "Authorization: Bearer sk_your_secret_key"

Response:

{
  "items": [
    {
      "user": {
        "id": "env_abc123:user-1",
        "name": "Alice Chen",
        "avatar": "https://example.com/avatars/alice.jpg",
        "color": "#6366f1"
      },
      "status": "online",
      "lastSeen": "2026-03-10T14:30:00.000Z"
    }
  ]
}

INFO

Presence is real-time state — it reflects who is connected right now, not historical data.