Quickstart

Ask who is in a room right now.

ProposedNot yet callable

This documents a design under review. Endpoints, payloads and field names may change before release.

Take a snapshot

A snapshot is a plain GET. It needs the presence:read scope, which is separate from the attendance scopes.

curl "https://api.onetaplabs.com/v1/presence?room=block-c-204" \
  -H "Authorization: Bearer $ONETAP_KEY"

{
  "object": "list",
  "as_of": "2026-07-19T09:22:04Z",
  "data": [
    {
      "student": { "id": "stu_2a77c1", "external_id": "2024CS118" },
      "room": "block-c-204",
      "state": "present",
      "first_seen_at": "2026-07-19T09:01:12Z",
      "last_seen_at": "2026-07-19T09:21:47Z",
      "confidence": "high"
    }
  ]
}

as_of is when the snapshot was taken. Show it wherever you show the data — a presence figure without a timestamp invites people to trust a stale screen.

Filters

Parameter	Type	Notes
room	string	Room slug. Omit for the whole institution.
session_id	string	Everyone present for a given session.
student_id	string	Narrow to one student.
state	enum	present \| recently_left — defaults to present only.

Snapshot or stream

Poll a snapshot when a periodic refresh is enough — a dashboard tile updating every 30 seconds. Subscribe to the stream when something has to react the moment a person moves, like a roll-call screen or an evacuation check.

Do not poll the snapshot every second. That is what the stream is for, and the rate limit will stop you anyway.