Appearance
Sessions API Reference
GET /api/v1/sessions
List recording sessions
Use to browse sessions, newest starts_at first. Query parameters: term_code, room_code, status (one of planned, starting, recording, stopping, completed, failed, canceled, missed), date=YYYY-MM-DD (a UTC calendar day matched against starts_at, independent of DISPATCH_TIMEZONE), course_code (scheduled sessions only, manual ones have no entry) and limit (default 100, clamped to 1000). An invalid status, date or limit answers 400 invalid_request. Sessions 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-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 |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 500 | internal_error | Internal Server Error |
GET /api/v1/sessions/{id}
Get a session
Use to fetch one session together with its photo ledger and the live upstream stream when a stream_id is stored. The upstream lookup is best-effort: a webcam-server outage degrades the response to the stored session instead of failing it. An unknown session answers 404 session_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 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",
"photos": [
{
"attempts": 1,
"camera_enum": 0,
"created_at": "2026-09-07T08:20:00+08:00",
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"id": "01J8ZG5PHO6R8U0W2Y4A6C8E0G2",
"photo_id": "01J8ZJ7PHO8T0W2Y4A6C8E0G2J4",
"request_id": "01J8ZH6REQ7S9V1X3Z5B7D9F1H3",
"resolved_at": "2026-09-07T08:20:04+08:00",
"room_code": "A301",
"session_id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"source": "manual",
"status": "resolved",
"taken_at": "2026-09-07T08:20:00+08:00"
}
],
"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": "recording",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"updated_at": "2026-09-07T00:00:02Z",
"upstream": {
"camera_enum": 0,
"device_id": "01J8Z4W3K5M7Q9R1T3V5X7Z9B1",
"id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1",
"started_at": "2026-09-07T07:58:02+08:00",
"status": "active"
}
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | session_not_found | Not Found |
| 500 | internal_error | Internal Server Error |
GET /api/v1/sessions/{id}/artifacts
List session artifacts
Use to enumerate a session's recorded segments and resolved photos. Segments are re-derived from GET /api/streams/{stream_id}/ on webcam-server and photos are resolved through the session's photo ledger; every download_url is minted by webcam-server for this response, is valid for about 15 minutes and is never cached by dispatchub, so request the artifacts again when a URL expires. A session without a stored stream_id reports its own status with empty lists, and an unreachable webcam-server answers 503 upstream_unavailable. The optional merge member is the session's merge job in smartclass-merge, which remuxes the segments into one playable video: status is pending until the job is submitted, submitted while it is polled, then succeeded or failed. On the succeeded member download_url is minted per response by filehouse - the service that owns the destination bucket - and is valid for about 15 minutes; dispatchub never caches it, so request the artifacts again when it expires. The URL is absent while the merge is not succeeded and while filehouse could not mint it (the member still reports the merge's state, and the failure is logged, never a 5xx). The object-storage coordinates that locate the merged video are never exposed: they stay in dispatchub's database, where download_url minting reads them. The member is absent while no merge was ever enqueued, which is also the case when merging is disabled; a failed ledger lookup is logged and leaves the member out instead of failing the call.
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 the session's room owner_id equal to the token subject.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"merge": {
"attempts": 1,
"created_at": "2026-09-07T01:40:11Z",
"download_url": "https://files.example.edu/recordings/merged/A301/2026-09-07/01J8ZD2SES3N5Q7S9U1W3Y5A7C9.mp4?X-Amz-Expires=900",
"id": "01J8ZM9MRG0S2U4W6Y8A0C2E4G6",
"job_id": "01J8ZN1JOB2T4V6X8Z0B2D4F6H8",
"session_id": "01J8ZD2SES3N5Q7S9U1W3Y5A7C9",
"size_bytes": 104857600,
"status": "succeeded",
"updated_at": "2026-09-07T01:52:30Z"
},
"photos": [
{
"download_url": "https://files.example.edu/webcam/photos/01J8ZJ7PHO8T0W2Y4A6C8E0G2J4?X-Amz-Expires=900",
"photo_id": "01J8ZJ7PHO8T0W2Y4A6C8E0G2J4",
"taken_at": "2026-09-07T08:20:00+08:00"
}
],
"segments": [
{
"download_url": "https://files.example.edu/webcam/segments/01J8ZF4STR5Q7T9V1X3Z5B7D9F1/1.bin?X-Amz-Expires=900",
"duration_ms": 6000,
"segment_seq": 1,
"size_bytes": 1048576
}
],
"status": "completed",
"stream_id": "01J8ZF4STR5Q7T9V1X3Z5B7D9F1"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | session_not_found | Not Found |
| 500 | internal_error | Internal Server Error |
| 503 | upstream_unavailable | Service Unavailable |