Skip to content

Rooms API Reference ​

GET /api/v1/rooms ​

List room bindings

Use to enumerate the room_code → (device_id, camera_enum) bindings. Pass limit to cap the number returned; the default is 100, values above 1000 are clamped and a non-positive or non-numeric limit answers 400 invalid_request. Rooms are not filtered by scope: collection routes require the any-scoped key: rows are returned unfiltered, so no narrower scope can grant access.

Required permission — dispatch:read:any

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "camera_enum": 0,
      "created_at": "2026-08-20T09:00:00Z",
      "device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
      "enabled": true,
      "name": "Building A / Room 301",
      "owner_id": "01J8Z1USER3Y5W7A9C1E3G5J7L9",
      "room_code": "A301",
      "team_id": "01J8Z2TEAM5A7C9E1G3J5L7N9P1",
      "updated_at": "2026-08-20T09:00:00Z"
    }
  ]
}

Errors ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
500internal_errorInternal Server Error

DELETE /api/v1/rooms/{room_code} ​

Unbind a room

Use to remove a room binding that nothing references. Once timetable or session history references the room the foreign keys keep the row alive, so the call answers 409 room_has_history and the operator should disable the binding instead with PUT /api/v1/rooms/{room_code} and {"enabled": false}, which takes it out of scheduling while keeping history readable. A successful delete answers 204 No Content; an unknown room answers 404 room_not_bound.

Required permission — dispatch:manage:any (or dispatch:manage:team scoped to the target team) own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.

Path parameters ​

ParameterDescription
room_codePath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication is requiredUnauthorized
403permission deniedForbidden
404room_not_boundNot Found
409room_has_historyConflict
500internal_errorInternal Server Error

PUT /api/v1/rooms/{room_code} ​

Bind a room

Use to bind a room_code to a webcam-server device and camera. The device is validated live with GET /api/devices/{device_id}/ on webcam-server and its team_id and owner_id are snapshotted onto the binding, because the permission ladder resolves against them; re-binding refreshes the snapshot. enabled defaults to true and can be set false to keep the binding without scheduling; it can be flipped at any time, even once the room has timetable or session history and can no longer be deleted (DELETE answers 409 room_has_history), so disabling is the supported way to take a used room out of service. The request answers 200 with the stored binding, 404 device_not_found when webcam-server does not know the device, 409 invalid_request when device_id and camera_enum are already bound to another room, and 503 upstream_unavailable when webcam-server cannot be reached.

Required permission — dispatch:manage:any (or dispatch:manage:team scoped to the target team) creating a new binding requires dispatch:manage:any; re-binding an existing room also accepts dispatch:manage:team or dispatch:manage:own when the room's ownership snapshot matches the caller.

Path parameters ​

ParameterDescription
room_codePath parameter.

Request body (application/json) ​

FieldTypeRequired
camera_enumintegerYes
device_idstringYes
enabledbooleanYes
namestringYes
json
{
  "camera_enum": 0,
  "device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
  "name": "Building A / Room 301"
}

Responses ​

  • 200 — Successful response
json
{
  "camera_enum": 0,
  "created_at": "2026-08-20T09:00:00Z",
  "device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
  "enabled": true,
  "name": "Building A / Room 301",
  "owner_id": "01J8Z1USER3Y5W7A9C1E3G5J7L9",
  "room_code": "A301",
  "team_id": "01J8Z2TEAM5A7C9E1G3J5L7N9P1",
  "updated_at": "2026-08-20T09:00:00Z"
}

Errors ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
404device_not_foundNot Found
409invalid_requestConflict
500internal_errorInternal Server Error
503upstream_unavailableService Unavailable

GET /api/v1/rooms/{room_code}/live ​

Get live room state

Use to fetch what the room's device is doing right now: online comes from webcam-server's device record, cameras lists the current registration's parameters and active_session is dispatchub's live session for the room when one exists. The call is proxied from webcam-server on every request, never cached; an unreachable upstream answers 503 upstream_unavailable and an unknown device 404 device_not_found.

Required permission — dispatch:read:any (or dispatch:read:team scoped to the target team) own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.

Path parameters ​

ParameterDescription
room_codePath parameter.

Responses ​

  • 200 — Successful response
json
{
  "active_session": {
    "id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
    "started_at": "2026-09-07T07:58:02+08:00",
    "stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1"
  },
  "cameras": [
    {
      "camera_enum": 0,
      "fps": 30,
      "resolution": "1920x1080",
      "supported_codec": [
        "h264",
        "mjpeg"
      ]
    }
  ],
  "online": true
}

Errors ​

StatusCodeDetail
401authentication is requiredUnauthorized
403permission deniedForbidden
404device_not_foundNot Found; Not Found
404room_not_boundNot Found; Not Found
500internal_errorInternal Server Error
503upstream_unavailableService Unavailable