Appearance
Recording API Reference
POST /api/v1/rooms/{room_code}/camera/switch
Switch the active camera
Use to make one of the room device's cameras active, legal at any time while the device is online. The body is {"camera_enum":N}. webcam-server queues the command and answers 202 Accepted with its command id; the device reports the outcome asynchronously, so dispatchub records the accepted command in camera_commands and the response is 202 with command_id and camera_enum. Failures: 400 invalid_request when camera_enum is missing or unknown to the device, 404 room_not_bound, 409 device_offline and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control: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. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| camera_enum | integer | Yes |
json
{
"camera_enum": 1
}Responses
- 200 — Successful response
json
{
"camera_enum": 1,
"command_id": "01J8ZK8CMD9U1W3Y5A7C9E1G3J5"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | room_not_bound | Not Found |
| 409 | device_offline | Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |
POST /api/v1/rooms/{room_code}/photo
Capture a snapshot
Use to ask the room device for a single still image; legal while a stream is live and while the room is idle (an idle capture is stored with no session). webcam-server answers 202 with a request id and mints the photo id only when the device uploads the image, so dispatchub writes a session_photos ledger row and resolves the photo id asynchronously by polling the device's photo list; the response is 202 with session_photo_id, request_id and status pending. Read the resolved photo through GET /api/v1/sessions/{id}/artifacts once its status becomes resolved. The request has no body; X-Idempotency-Key is accepted. Failures: 404 room_not_bound, 409 device_offline and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control: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
{
"request_id": "01J8ZH6REQ7S9V1X3Z5B7D9F1H3",
"session_photo_id": "01J8ZG5PHO6R8U0W2Y4A6C8E0G2",
"status": "pending"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | room_not_bound | Not Found |
| 409 | device_offline | Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |
POST /api/v1/rooms/{room_code}/recording/start
Start an ad-hoc recording
Use to start recording a room outside its timetable. The scheduler creates a manual session for the room's binding, calls webcam-server's recording/start and stores the stream_id; the manual session ends when it is stopped explicitly (there is no scheduled end). The request answers 201 Created with the new session and its Location header. It has no body; send X-Idempotency-Key to make it replayable. Failures: 404 room_not_bound, 409 device_offline, 409 already_streaming, 409 duplicate_idempotency_key and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control: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
{
"camera_enum": 0,
"created_at": "2026-08-21T10:30:00Z",
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"ends_at": "2026-09-07T09:40:00+08:00",
"entry_id": "01J8ZE3ENT4P6R8T0V2X4Z6B8D0",
"id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"origin": "schedule",
"retry_count": 0,
"room_code": "A301",
"started_at": "2026-09-07T07:58:02+08:00",
"starts_at": "2026-09-07T08:00:00+08:00",
"status": "completed",
"stopped_at": "2026-09-07T09:40:11+08:00",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"updated_at": "2026-09-07T01:40:11Z"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | room_not_bound | Not Found |
| 409 | already_streaming | Conflict; Conflict; Conflict |
| 409 | device_offline | Conflict; Conflict; Conflict |
| 409 | duplicate_idempotency_key | Conflict; Conflict; Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |
POST /api/v1/rooms/{room_code}/recording/stop
Stop the room's live recording
Use to stop whichever session is live in the room, scheduled or manual. The request has no body and answers 200 with the stopped session; X-Idempotency-Key behaves as on start. Failures: 404 room_not_bound, 404 no_active_stream, 409 device_offline, 409 duplicate_idempotency_key and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control: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
{
"camera_enum": 0,
"created_at": "2026-08-21T10:30:00Z",
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"ends_at": "2026-09-07T09:40:00+08:00",
"entry_id": "01J8ZE3ENT4P6R8T0V2X4Z6B8D0",
"id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"origin": "schedule",
"retry_count": 0,
"room_code": "A301",
"started_at": "2026-09-07T07:58:02+08:00",
"starts_at": "2026-09-07T08:00:00+08:00",
"status": "completed",
"stopped_at": "2026-09-07T09:40:11+08:00",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"updated_at": "2026-09-07T01:40:11Z"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | no_active_stream | Not Found; Not Found |
| 404 | room_not_bound | Not Found; Not Found |
| 409 | device_offline | Conflict; Conflict |
| 409 | duplicate_idempotency_key | Conflict; Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |
POST /api/v1/sessions/{id}/recording/start
Start a session recording
Use for the manual early start of a planned session or to retry a failed one. The scheduler claims the session, calls webcam-server's recording/start and stores the returned stream_id; the request answers 200 with the updated session. Send X-Idempotency-Key to make the call replayable: the first accepted command is stored in camera_commands and a replayed key does not issue a second upstream command (a conflicting reuse answers 409 duplicate_idempotency_key). Other failures: 409 session_not_planned, 409 device_offline, 409 already_streaming when the camera is already recording, 404 session_not_found and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control:team scoped to the target team) own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"camera_enum": 0,
"created_at": "2026-08-21T10:30:00Z",
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"ends_at": "2026-09-07T09:40:00+08:00",
"entry_id": "01J8ZE3ENT4P6R8T0V2X4Z6B8D0",
"id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"origin": "schedule",
"retry_count": 0,
"room_code": "A301",
"started_at": "2026-09-07T07:58:02+08:00",
"starts_at": "2026-09-07T08:00:00+08:00",
"status": "completed",
"stopped_at": "2026-09-07T09:40:11+08:00",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"updated_at": "2026-09-07T01:40:11Z"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | session_not_found | Not Found |
| 409 | already_streaming | Conflict; Conflict; Conflict; Conflict |
| 409 | device_offline | Conflict; Conflict; Conflict; Conflict |
| 409 | duplicate_idempotency_key | Conflict; Conflict; Conflict; Conflict |
| 409 | session_not_planned | Conflict; Conflict; Conflict; Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |
POST /api/v1/sessions/{id}/recording/stop
Stop a session recording
Use to end a session's recording before its scheduled end. The scheduler calls webcam-server's recording/stop, stores ended_at as stopped_at and marks the session completed; a stream that already finished upstream counts as success and the stored stream row is reconciled instead. The request answers 200 with the updated session; X-Idempotency-Key behaves as on start. Other failures: 404 session_not_found, 404 no_active_stream, 409 device_offline, 409 duplicate_idempotency_key and 503 upstream_unavailable.
Required permission — dispatch:control:any (or dispatch:control:team scoped to the target team) own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"camera_enum": 0,
"created_at": "2026-08-21T10:30:00Z",
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"ends_at": "2026-09-07T09:40:00+08:00",
"entry_id": "01J8ZE3ENT4P6R8T0V2X4Z6B8D0",
"id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"origin": "schedule",
"retry_count": 0,
"room_code": "A301",
"started_at": "2026-09-07T07:58:02+08:00",
"starts_at": "2026-09-07T08:00:00+08:00",
"status": "completed",
"stopped_at": "2026-09-07T09:40:11+08:00",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"updated_at": "2026-09-07T01:40:11Z"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | no_active_stream | Not Found; Not Found |
| 404 | session_not_found | Not Found; Not Found |
| 409 | device_offline | Conflict; Conflict |
| 409 | duplicate_idempotency_key | Conflict; Conflict |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |