Skip to content

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 ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
500internal_errorInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication is requiredUnauthorized
403permission deniedForbidden
404session_not_foundNot Found
500internal_errorInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication is requiredUnauthorized
403permission deniedForbidden
404session_not_foundNot Found
500internal_errorInternal Server Error
503upstream_unavailableService Unavailable