Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 500 | internal_error | Internal 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
| Parameter | Description |
|---|---|
| room_code | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | room_not_bound | Not Found |
| 409 | room_has_history | Conflict |
| 500 | internal_error | Internal 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
| Parameter | Description |
|---|---|
| room_code | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| camera_enum | integer | Yes |
| device_id | string | Yes |
| enabled | boolean | Yes |
| name | string | Yes |
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
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | device_not_found | Not Found |
| 409 | invalid_request | Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service 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
| Parameter | Description |
|---|---|
| room_code | Path 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
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | device_not_found | Not Found; Not Found |
| 404 | room_not_bound | Not Found; Not Found |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |