openapi: 3.1.0
info:
  title: SmartClass Dispatch Hub API
  version: 0.1.0
servers:
  - url: http://localhost:8081
    description: Local server (default DISPATCH_LISTEN_ADDR)
tags:
  - Health
  - Recording
  - Rooms
  - Sessions
  - Terms
  - Timetable
paths:
  /api/v1/rooms:
    get:
      tags:
        - Rooms
      summary: List room bindings
      description: '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.'
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        camera_enum:
                          type: integer
                        created_at:
                          format: date-time
                          type: string
                        device_id:
                          type: string
                        enabled:
                          type: boolean
                        name:
                          type: string
                        owner_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        room_code:
                          type: string
                        team_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        updated_at:
                          format: date-time
                          type: string
                      required:
                        - room_code
                        - name
                        - device_id
                        - camera_enum
                        - enabled
                        - created_at
                        - updated_at
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                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"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
  /api/v1/rooms/{room_code}:
    delete:
      tags:
        - Rooms
      summary: Unbind a room
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: room_not_bound
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: room_has_history
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:manage:any
        team: dispatch:manage:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
    put:
      tags:
        - Rooms
      summary: Bind a room
      description: 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.
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                camera_enum:
                  anyOf:
                    - type: integer
                    - type: "null"
                device_id:
                  type: string
                enabled:
                  anyOf:
                    - type: boolean
                    - type: "null"
                name:
                  type: string
              required:
                - name
                - device_id
                - camera_enum
                - enabled
              type: object
            example:
              camera_enum: 0
              device_id: 01J8Z4W3K5M7Q9R1T3V5X7Z9B1
              name: Building A / Room 301
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  device_id:
                    type: string
                  enabled:
                    type: boolean
                  name:
                    type: string
                  owner_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  room_code:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - room_code
                  - name
                  - device_id
                  - camera_enum
                  - enabled
                  - created_at
                  - updated_at
                type: object
              example:
                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"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: device_not_found
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: invalid_request
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:manage:any
        team: dispatch:manage:team
        note: 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.
  /api/v1/rooms/{room_code}/camera/switch:
    post:
      tags:
        - Recording
      summary: Switch the active camera
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                camera_enum:
                  anyOf:
                    - type: integer
                    - type: "null"
              required:
                - camera_enum
              type: object
            example:
              camera_enum: 1
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  command_id:
                    type: string
                required:
                  - command_id
                  - camera_enum
                type: object
              example:
                camera_enum: 1
                command_id: 01J8ZK8CMD9U1W3Y5A7C9E1G3J5
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: room_not_bound
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: device_offline
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
  /api/v1/rooms/{room_code}/live:
    get:
      tags:
        - Rooms
      summary: Get live room state
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active_session:
                    anyOf:
                      - properties:
                          id:
                            type: string
                          started_at:
                            anyOf:
                              - format: date-time
                                type: string
                              - type: "null"
                          stream_id:
                            anyOf:
                              - type: string
                              - type: "null"
                        required:
                          - id
                        type: object
                      - type: "null"
                  cameras:
                    items:
                      properties:
                        camera_enum:
                          type: integer
                        fps:
                          type: integer
                        resolution:
                          type: string
                        supported_codec:
                          items:
                            type: string
                          type: array
                      required:
                        - camera_enum
                        - resolution
                        - fps
                        - supported_codec
                      type: object
                    type: array
                  online:
                    type: boolean
                required:
                  - online
                  - cameras
                type: object
              example:
                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
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found; Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                room_not_bound:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: room_not_bound
                device_not_found:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: device_not_found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
        team: dispatch:read:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
  /api/v1/rooms/{room_code}/photo:
    post:
      tags:
        - Recording
      summary: Capture a snapshot
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  request_id:
                    type: string
                  session_photo_id:
                    type: string
                  status:
                    type: string
                required:
                  - session_photo_id
                  - request_id
                  - status
                type: object
              example:
                request_id: 01J8ZH6REQ7S9V1X3Z5B7D9F1H3
                session_photo_id: 01J8ZG5PHO6R8U0W2Y4A6C8E0G2
                status: pending
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: room_not_bound
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: device_offline
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
  /api/v1/rooms/{room_code}/recording/start:
    post:
      tags:
        - Recording
      summary: Start an ad-hoc recording
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  device_id:
                    type: string
                  ends_at:
                    format: date-time
                    type: string
                  entry_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  last_error:
                    anyOf:
                      - type: string
                      - type: "null"
                  origin:
                    type: string
                  retry_count:
                    type: integer
                  room_code:
                    type: string
                  started_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  starts_at:
                    format: date-time
                    type: string
                  status:
                    type: string
                  stopped_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  stream_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - room_code
                  - device_id
                  - camera_enum
                  - starts_at
                  - ends_at
                  - status
                  - origin
                  - retry_count
                  - created_at
                  - updated_at
                type: object
              example:
                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"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: room_not_bound
        "409":
          description: Conflict; Conflict; Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                device_offline:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: device_offline
                already_streaming:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: already_streaming
                duplicate_idempotency_key:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: duplicate_idempotency_key
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
  /api/v1/rooms/{room_code}/recording/stop:
    post:
      tags:
        - Recording
      summary: Stop the room's live recording
      description: '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.'
      parameters:
        - name: room_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  device_id:
                    type: string
                  ends_at:
                    format: date-time
                    type: string
                  entry_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  last_error:
                    anyOf:
                      - type: string
                      - type: "null"
                  origin:
                    type: string
                  retry_count:
                    type: integer
                  room_code:
                    type: string
                  started_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  starts_at:
                    format: date-time
                    type: string
                  status:
                    type: string
                  stopped_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  stream_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - room_code
                  - device_id
                  - camera_enum
                  - starts_at
                  - ends_at
                  - status
                  - origin
                  - retry_count
                  - created_at
                  - updated_at
                type: object
              example:
                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"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found; Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                room_not_bound:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: room_not_bound
                no_active_stream:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: no_active_stream
        "409":
          description: Conflict; Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                device_offline:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: device_offline
                duplicate_idempotency_key:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: duplicate_idempotency_key
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and rooms.owner_id equal to the token subject.
  /api/v1/sessions:
    get:
      tags:
        - Sessions
      summary: List recording sessions
      description: '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.'
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        camera_enum:
                          type: integer
                        created_at:
                          format: date-time
                          type: string
                        device_id:
                          type: string
                        ends_at:
                          format: date-time
                          type: string
                        entry_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                        last_error:
                          anyOf:
                            - type: string
                            - type: "null"
                        origin:
                          type: string
                        retry_count:
                          type: integer
                        room_code:
                          type: string
                        started_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        starts_at:
                          format: date-time
                          type: string
                        status:
                          type: string
                        stopped_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        stream_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        updated_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - room_code
                        - device_id
                        - camera_enum
                        - starts_at
                        - ends_at
                        - status
                        - origin
                        - retry_count
                        - created_at
                        - updated_at
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                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"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
  /api/v1/sessions/{id}:
    get:
      tags:
        - Sessions
      summary: Get a session
      description: '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.'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  Session:
                    properties:
                      camera_enum:
                        type: integer
                      created_at:
                        format: date-time
                        type: string
                      device_id:
                        type: string
                      ends_at:
                        format: date-time
                        type: string
                      entry_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                      last_error:
                        anyOf:
                          - type: string
                          - type: "null"
                      origin:
                        type: string
                      retry_count:
                        type: integer
                      room_code:
                        type: string
                      started_at:
                        anyOf:
                          - format: date-time
                            type: string
                          - type: "null"
                      starts_at:
                        format: date-time
                        type: string
                      status:
                        type: string
                      stopped_at:
                        anyOf:
                          - format: date-time
                            type: string
                          - type: "null"
                      stream_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      updated_at:
                        format: date-time
                        type: string
                    required:
                      - id
                      - room_code
                      - device_id
                      - camera_enum
                      - starts_at
                      - ends_at
                      - status
                      - origin
                      - retry_count
                      - created_at
                      - updated_at
                    type: object
                  photos:
                    items:
                      properties:
                        actor_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        attempts:
                          type: integer
                        camera_enum:
                          type: integer
                        created_at:
                          format: date-time
                          type: string
                        device_id:
                          type: string
                        id:
                          type: string
                        next_poll_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        photo_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        request_id:
                          type: string
                        resolved_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        room_code:
                          type: string
                        session_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        source:
                          type: string
                        status:
                          type: string
                        taken_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - room_code
                        - device_id
                        - camera_enum
                        - request_id
                        - source
                        - status
                        - attempts
                        - taken_at
                        - created_at
                      type: object
                    type: array
                  upstream:
                    anyOf:
                      - properties:
                          camera_enum:
                            type: integer
                          device_id:
                            type: string
                          ended_at:
                            anyOf:
                              - format: date-time
                                type: string
                              - type: "null"
                          id:
                            type: string
                          metadata:
                            properties:
                              codec:
                                type: string
                              codecs:
                                items:
                                  type: string
                                type: array
                              fps:
                                type: integer
                              resolution:
                                type: string
                            type: object
                          started_at:
                            format: date-time
                            type: string
                          status:
                            type: string
                        required:
                          - id
                          - device_id
                          - camera_enum
                          - status
                          - started_at
                          - metadata
                        type: object
                      - type: "null"
                required:
                  - Session
                  - photos
                type: object
              example:
                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
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: session_not_found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
        team: dispatch:read:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
  /api/v1/sessions/{id}/artifacts:
    get:
      tags:
        - Sessions
      summary: List session artifacts
      description: '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.'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  merge:
                    anyOf:
                      - properties:
                          attempts:
                            type: integer
                          created_at:
                            format: date-time
                            type: string
                          download_url:
                            type: string
                          id:
                            type: string
                          job_id:
                            anyOf:
                              - type: string
                              - type: "null"
                          last_error:
                            anyOf:
                              - type: string
                              - type: "null"
                          session_id:
                            type: string
                          size_bytes:
                            anyOf:
                              - type: integer
                              - type: "null"
                          status:
                            type: string
                          updated_at:
                            format: date-time
                            type: string
                        required:
                          - id
                          - session_id
                          - status
                          - attempts
                          - created_at
                          - updated_at
                        type: object
                      - type: "null"
                  photos:
                    items:
                      properties:
                        download_url:
                          type: string
                        photo_id:
                          type: string
                        taken_at:
                          format: date-time
                          type: string
                      required:
                        - photo_id
                        - taken_at
                        - download_url
                      type: object
                    type: array
                  segments:
                    items:
                      properties:
                        download_url:
                          type: string
                        duration_ms:
                          anyOf:
                            - type: integer
                            - type: "null"
                        segment_seq:
                          type: integer
                        size_bytes:
                          type: integer
                      required:
                        - segment_seq
                        - size_bytes
                        - download_url
                      type: object
                    type: array
                  status:
                    type: string
                  stream_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - status
                  - segments
                  - photos
                type: object
              example:
                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
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: session_not_found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
        team: dispatch:read:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
  /api/v1/sessions/{id}/recording/start:
    post:
      tags:
        - Recording
      summary: Start a session recording
      description: '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.'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  device_id:
                    type: string
                  ends_at:
                    format: date-time
                    type: string
                  entry_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  last_error:
                    anyOf:
                      - type: string
                      - type: "null"
                  origin:
                    type: string
                  retry_count:
                    type: integer
                  room_code:
                    type: string
                  started_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  starts_at:
                    format: date-time
                    type: string
                  status:
                    type: string
                  stopped_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  stream_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - room_code
                  - device_id
                  - camera_enum
                  - starts_at
                  - ends_at
                  - status
                  - origin
                  - retry_count
                  - created_at
                  - updated_at
                type: object
              example:
                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"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: session_not_found
        "409":
          description: Conflict; Conflict; Conflict; Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                session_not_planned:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: session_not_planned
                device_offline:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: device_offline
                already_streaming:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: already_streaming
                duplicate_idempotency_key:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: duplicate_idempotency_key
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
  /api/v1/sessions/{id}/recording/stop:
    post:
      tags:
        - Recording
      summary: Stop a session recording
      description: '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.'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  camera_enum:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  device_id:
                    type: string
                  ends_at:
                    format: date-time
                    type: string
                  entry_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  last_error:
                    anyOf:
                      - type: string
                      - type: "null"
                  origin:
                    type: string
                  retry_count:
                    type: integer
                  room_code:
                    type: string
                  started_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  starts_at:
                    format: date-time
                    type: string
                  status:
                    type: string
                  stopped_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  stream_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - room_code
                  - device_id
                  - camera_enum
                  - starts_at
                  - ends_at
                  - status
                  - origin
                  - retry_count
                  - created_at
                  - updated_at
                type: object
              example:
                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"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found; Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                session_not_found:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: session_not_found
                no_active_stream:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: no_active_stream
        "409":
          description: Conflict; Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                device_offline:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: device_offline
                duplicate_idempotency_key:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: duplicate_idempotency_key
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:control:any
        team: dispatch:control:team
        note: own-scoped access additionally requires the corresponding dispatch:*:own key and the session's room owner_id equal to the token subject.
  /api/v1/terms:
    get:
      tags:
        - Terms
      summary: List terms
      description: 'Use to enumerate the teaching terms. 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. Terms are not filtered by scope: collection routes require the any-scoped key: rows are returned unfiltered, so no narrower scope can grant access.'
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        name:
                          type: string
                        term_code:
                          type: string
                        updated_at:
                          format: date-time
                          type: string
                        week1_monday:
                          format: date-time
                          type: string
                        weeks:
                          type: integer
                      required:
                        - term_code
                        - name
                        - week1_monday
                        - weeks
                        - created_at
                        - updated_at
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                items:
                  - created_at: "2026-08-20T09:00:00Z"
                    name: 2026 秋季学期
                    term_code: 2026-FALL
                    updated_at: "2026-08-20T09:00:00Z"
                    week1_monday: "2026-09-07T00:00:00Z"
                    weeks: 16
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
    post:
      tags:
        - Terms
      summary: Create or replace a term
      description: Use to create a term or replace its fields. term_code identifies the term, week1_monday is the Monday of teaching week 1 as YYYY-MM-DD and weeks counts teaching weeks (1-30). Posting an existing term_code replaces name, week1_monday and weeks, which keeps a corrected re-import deterministic. The request answers 201 Created with the stored term.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                term_code:
                  type: string
                week1_monday:
                  type: string
                weeks:
                  anyOf:
                    - type: integer
                    - type: "null"
              required:
                - term_code
                - name
                - week1_monday
                - weeks
              type: object
            example:
              name: 2026 秋季学期
              term_code: 2026-FALL
              week1_monday: "2026-09-07"
              weeks: 16
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  name:
                    type: string
                  term_code:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  week1_monday:
                    format: date-time
                    type: string
                  weeks:
                    type: integer
                required:
                  - term_code
                  - name
                  - week1_monday
                  - weeks
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-08-20T09:00:00Z"
                name: 2026 秋季学期
                term_code: 2026-FALL
                updated_at: "2026-08-20T09:00:00Z"
                week1_monday: "2026-09-07T00:00:00Z"
                weeks: 16
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: invalid_request
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:manage:any
  /api/v1/terms/{term_code}/periods:
    get:
      tags:
        - Terms
      summary: Get a term's period table
      description: Use to fetch the term's 节次 table. Periods define the wall-clock window of every period_no; imports validate rows against them. A term without a configured table answers 404 periods_not_configured instead of an empty list.
      parameters:
        - name: term_code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        end_time:
                          type: string
                        period_no:
                          type: integer
                        start_time:
                          type: string
                      required:
                        - period_no
                        - start_time
                        - end_time
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                items:
                  - end_time: 08:45
                    period_no: 1
                    start_time: 08:00
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found; Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                term_not_found:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: term_not_found
                periods_not_configured:
                  value:
                    type: about:blank
                    title: Not Found
                    status: 404
                    detail: periods_not_configured
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
    put:
      tags:
        - Terms
      summary: Replace a term's period table
      description: Use to replace the term's whole 节次 table in one call. The body is {"periods":[{"period_no":N,"start_time":"HH:MM","end_time":"HH:MM"}]}; period_no must be 1-20 and unique, both times are HH:MM local time and end_time must be after start_time. The period numbers of existing sessions are not re-validated, so re-import a term's timetable after changing its table. The response is 200 with the replaced table.
      parameters:
        - name: term_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                periods:
                  items:
                    properties:
                      end_time:
                        type: string
                      period_no:
                        type: integer
                      start_time:
                        type: string
                    required:
                      - period_no
                      - start_time
                      - end_time
                    type: object
                  type: array
              required:
                - periods
              type: object
            example:
              periods:
                - end_time: 08:45
                  period_no: 1
                  start_time: 08:00
                - end_time: 09:40
                  period_no: 2
                  start_time: 08:55
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        end_time:
                          type: string
                        period_no:
                          type: integer
                        start_time:
                          type: string
                      required:
                        - period_no
                        - start_time
                        - end_time
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                items:
                  - end_time: 08:45
                    period_no: 1
                    start_time: 08:00
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: term_not_found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:manage:any
  /api/v1/timetable/imports:
    get:
      tags:
        - Timetable
      summary: List import batches
      description: Use to review the import history, newest first. Pass term_code to restrict the list to one term and 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. Each batch carries its status (dry_run, committed or failed), row counts and the per-row error list of the failed attempt.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        error_count:
                          type: integer
                        errors:
                          items:
                            properties:
                              code:
                                type: string
                              column:
                                type: string
                              message:
                                type: string
                              row:
                                type: integer
                            required:
                              - row
                              - code
                              - message
                            type: object
                          type: array
                        filename:
                          type: string
                        id:
                          type: string
                        imported_by:
                          type: string
                        mode:
                          type: string
                        ok_count:
                          type: integer
                        row_count:
                          type: integer
                        sha256:
                          type: string
                        status:
                          type: string
                        term_code:
                          type: string
                      required:
                        - id
                        - term_code
                        - mode
                        - filename
                        - sha256
                        - row_count
                        - ok_count
                        - error_count
                        - errors
                        - status
                        - imported_by
                        - created_at
                      type: object
                    type: array
                required:
                  - items
                type: object
              example:
                items:
                  - created_at: "2026-08-21T10:30:00Z"
                    error_count: 0
                    errors: []
                    filename: timetable-2026-fall.csv
                    id: 01J8ZC1IMP2M4P6R8T0V2X4Z6B8
                    imported_by: 01J8Z1USER3Y5W7A9C1E3G5J7L9
                    mode: replace
                    ok_count: 3
                    row_count: 3
                    sha256: 9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d
                    status: committed
                    term_code: 2026-FALL
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
    post:
      tags:
        - Timetable
      summary: Import a timetable CSV
      description: 'Use to upload one term''s timetable as a multipart/form-data body whose single file part is named file (text/csv, at most 1 MiB and at most DISPATCH_MAX_IMPORT_ROWS data rows, default 5000). The header row is mandatory and matched by name in any order: term_code,course_code,course_name,teacher_username,room_code,weekday,period_start,period_end,weeks; unknown or missing columns reject the whole file. Every row must carry the same term_code, the term must exist, its 节次 table must cover period_start..period_end, room_code must be a bound enabled room and weeks must stay within the term''s teaching weeks. Overlapping rows for the same room, weekday, period range and weeks are rejected; a teacher double-booking is not. A row whose occurrences collide with an existing live or planned recording on the same (device_id, camera_enum) is rejected with code session_collision, because one camera cannot record two sessions at once; in replace mode the batch''s own term is excluded from that check, since the commit supersedes its pending sessions, while an append import still collides with them. Query parameters: mode=replace|append (default replace; replace supersedes the term''s previous entries and cancels their future planned sessions, already started or completed sessions are never touched), dry_run=true (validate only, no entries or sessions are written) and force=true (commit even though the same sha256 was already committed for the term). A dry run answers 200 with the stored batch object plus a preview array ([{row,course_code,session_count,first_starts_at,last_ends_at}]) so a wrong week1_monday or period table is visible before anything is written; a commit answers 201 Created with the stored batch and a Location header; a blocking row error answers 422 with detail import_validation_failed and the full errors array ([{row,column,code,message}]) while writing the batch with status failed and nothing else; a teacher double-booking is a non-blocking warning that is stored in the batch errors array without rejecting the file, so a committed batch can carry warnings and error_count counts every reported entry; an identical already-committed file answers 409 duplicate_import unless force=true.'
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  Import:
                    properties:
                      created_at:
                        format: date-time
                        type: string
                      error_count:
                        type: integer
                      errors:
                        items:
                          properties:
                            code:
                              type: string
                            column:
                              type: string
                            message:
                              type: string
                            row:
                              type: integer
                          required:
                            - row
                            - code
                            - message
                          type: object
                        type: array
                      filename:
                        type: string
                      id:
                        type: string
                      imported_by:
                        type: string
                      mode:
                        type: string
                      ok_count:
                        type: integer
                      row_count:
                        type: integer
                      sha256:
                        type: string
                      status:
                        type: string
                      term_code:
                        type: string
                    required:
                      - id
                      - term_code
                      - mode
                      - filename
                      - sha256
                      - row_count
                      - ok_count
                      - error_count
                      - errors
                      - status
                      - imported_by
                      - created_at
                    type: object
                  preview:
                    items:
                      properties:
                        course_code:
                          type: string
                        first_starts_at:
                          format: date-time
                          type: string
                        last_ends_at:
                          format: date-time
                          type: string
                        row:
                          type: integer
                        session_count:
                          type: integer
                      required:
                        - row
                        - course_code
                        - session_count
                        - first_starts_at
                        - last_ends_at
                      type: object
                    type: array
                required:
                  - Import
                type: object
              example:
                created_at: "2026-08-21T10:30:00Z"
                error_count: 0
                errors: []
                filename: timetable-2026-fall.csv
                id: 01J8ZC1IMP2M4P6R8T0V2X4Z6B8
                imported_by: 01J8Z1USER3Y5W7A9C1E3G5J7L9
                mode: replace
                ok_count: 3
                preview:
                  - course_code: CS101
                    first_starts_at: "2026-09-07T08:00:00+08:00"
                    last_ends_at: "2026-12-21T09:40:00+08:00"
                    row: 2
                    session_count: 16
                row_count: 3
                sha256: 9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d
                status: dry_run
                term_code: 2026-FALL
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: term_not_found
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: duplicate_import
        "422":
          description: Unprocessable Content; Unprocessable Content
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                session_collision:
                  value:
                    type: about:blank
                    title: Unprocessable Content
                    status: 422
                    detail: session_collision
                import_validation_failed:
                  value:
                    type: about:blank
                    title: Unprocessable Content
                    status: 422
                    detail: import_validation_failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:manage:any
  /api/v1/timetable/imports/{id}:
    get:
      tags:
        - Timetable
      summary: Get an import batch
      description: Use to fetch one batch together with the per-row errors of a failed validation, so the operator can correct the CSV. An unknown batch id answers 404 invalid_request.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  error_count:
                    type: integer
                  errors:
                    items:
                      properties:
                        code:
                          type: string
                        column:
                          type: string
                        message:
                          type: string
                        row:
                          type: integer
                      required:
                        - row
                        - code
                        - message
                      type: object
                    type: array
                  filename:
                    type: string
                  id:
                    type: string
                  imported_by:
                    type: string
                  mode:
                    type: string
                  ok_count:
                    type: integer
                  row_count:
                    type: integer
                  sha256:
                    type: string
                  status:
                    type: string
                  term_code:
                    type: string
                required:
                  - id
                  - term_code
                  - mode
                  - filename
                  - sha256
                  - row_count
                  - ok_count
                  - error_count
                  - errors
                  - status
                  - imported_by
                  - created_at
                type: object
              example:
                created_at: "2026-08-21T10:30:00Z"
                error_count: 0
                errors: []
                filename: timetable-2026-fall.csv
                id: 01J8ZC1IMP2M4P6R8T0V2X4Z6B8
                imported_by: 01J8Z1USER3Y5W7A9C1E3G5J7L9
                mode: replace
                ok_count: 3
                row_count: 3
                sha256: 9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d
                status: committed
                term_code: 2026-FALL
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid_request
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: permission denied
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: internal_error
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: dispatch:read:any
  /healthz:
    get:
      tags:
        - Health
      summary: Check liveness
      description: Use this unauthenticated probe to decide whether the HTTP process is alive. It never touches PostgreSQL or webcam-server, so it keeps answering ok during an upstream outage and is safe to call on a short interval.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                required:
                  - status
                type: object
              example:
                status: ok
      security: []
  /readyz:
    get:
      tags:
        - Health
      summary: Check readiness
      description: Use this unauthenticated probe on the operator dashboard. It pings PostgreSQL and calls webcam-server's /readyz with a 5-second timeout; both must answer, otherwise the probe reports 503 with detail upstream_unavailable and names the unreachable dependencies in the reason member.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                required:
                  - status
                type: object
              example:
                status: ready
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: upstream_unavailable
      security: []
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      required:
        - type
        - title
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: EdDSA JWT
