c64bridge 0.9.2 → 1.0.0

package/doc/c64u/c64-openapi.yaml

@@ -1,30 +1,143 @@
 openapi: 3.1.0
 info:
-  title: Ultimate 64 REST API
-  version: "1.0.0"
-  summary: REST interface exposed by Ultimate 64 / 1541 Ultimate firmware ≥ 3.11.
+  title: Ultimate 64 Elite REST API
+  version: 3.15-alpha
+  summary: REST API exposed by the Ultimate 64 Elite 3.15 alpha firmware.
   description: |
-    This OpenAPI document captures the public HTTP interface described in the
-    official Ultimate 64 REST API documentation at
-    https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html.
-    Responses always include an `errors` array unless noted. When a network
-    password is configured, clients must supply the `X-Password` header on every
-    request. Example payloads were captured against a local Ultimate 64 Elite
-    reachable as `http://c64u` running firmware 3.12a.
+    Source-derived OpenAPI description for the HTTP API implemented in
+    `/software/api` of the 1541ultimate firmware tree.
+
+    The firmware exposes a single `v1` API version. JSON responses include an
+    `errors` array. Binary endpoints return `application/octet-stream` on
+    success and JSON with `errors` when the request cannot be completed.
+
+    If a network password is configured on the device, every API request must
+    include the `X-Password` header. If no network password is configured, the
+    same endpoints are available without the header.
 servers:
-  - url: http://c64u
-    description: Ultimate 64 on the local network (example fixture)
+  - url: http://u64
+    description: Ultimate 64 Elite on the local network
+  - url: http://{host}
+    description: Custom Ultimate host or IP address
+    variables:
+      host:
+        default: u64
+tags:
+  - name: System
+  - name: Runners
+  - name: Configuration
+  - name: Machine
+  - name: Drives
+  - name: Streams
+  - name: Files
+  - name: Input
+security:
+  - NetworkPassword: []
+  - {}
 components:
   securitySchemes:
     NetworkPassword:
       type: apiKey
       in: header
       name: X-Password
+      description: Required only when the device network password is configured.
+  parameters:
+    Category:
+      name: category
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Configuration category name or firmware wildcard pattern.
+    Item:
+      name: item
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Configuration item name or firmware wildcard pattern.
+    Setting:
+      name: setting
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Configuration value carried as the third path segment.
+    Drive:
+      name: drive
+      in: path
+      required: true
+      schema:
+        type: string
+        enum: [a, b]
+      description: Internal drive slot.
+    FilePath:
+      name: path
+      in: path
+      required: true
+      allowReserved: true
+      schema:
+        type: string
+      description: Device filesystem path below `/v1/files/`; URL-encode reserved characters.
+    Address:
+      name: address
+      in: query
+      required: true
+      schema:
+        type: string
+        pattern: "^(0x)?[0-9A-Fa-f]{1,4}$"
+      description: C64 address in hexadecimal.
+    Length:
+      name: length
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 0
+        maximum: 65536
+        default: 256
+    FileQuery:
+      name: file
+      in: query
+      required: true
+      schema:
+        type: string
+      description: Absolute or device-relative file path.
+    SongNumber:
+      name: songnr
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 0
+        default: 0
+    DiskName:
+      name: diskname
+      in: query
+      required: false
+      schema:
+        type: string
+    D64Tracks:
+      name: tracks
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 35
+        maximum: 41
+        default: 35
+    DnpTracks:
+      name: tracks
+      in: query
+      required: true
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 255
   schemas:
-    ErrorResponse:
+    ErrorList:
       type: object
-      required:
-        - errors
+      required: [errors]
       properties:
         errors:
           type: array
@@ -32,116 +145,159 @@ components:
             type: string
     VersionResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
-          required:
-            - version
+          required: [version]
           properties:
             version:
               type: string
+              example: "0.1"
     InfoResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
+          required: [product, firmware_version, fpga_version, hostname]
           properties:
             product:
               type: string
+              example: Ultimate 64 Elite
             firmware_version:
               type: string
+              example: 3.15 alpha
             fpga_version:
               type: string
+              example: "122"
             core_version:
               type: string
-              description: Present on Ultimate 64 devices.
+              description: Present on Ultimate 64-class firmware builds.
+              example: 1.4B
             hostname:
               type: string
             unique_id:
               type: string
-    ConfigListResponse:
+    ConfigCategoriesResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
+          required: [categories]
           properties:
             categories:
               type: array
               items:
                 type: string
+    ConfigValue:
+      oneOf:
+        - type: string
+        - type: integer
+    ConfigItemDetail:
+      type: object
+      required: [current]
+      properties:
+        current:
+          $ref: "#/components/schemas/ConfigValue"
+        values:
+          type: array
+          items:
+            type: string
+        presets:
+          type: array
+          items:
+            type: string
+        min:
+          type: integer
+        max:
+          type: integer
+        format:
+          type: string
+        default:
+          $ref: "#/components/schemas/ConfigValue"
+      additionalProperties: true
     ConfigCategoryResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-        - type: object
-          additionalProperties:
-            type: object
-    ConfigItemResponse:
-      allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
           additionalProperties:
             type: object
-    MemoryReadJson:
+            additionalProperties:
+              oneOf:
+                - $ref: "#/components/schemas/ConfigValue"
+                - $ref: "#/components/schemas/ConfigItemDetail"
+    ConfigBatchUpdate:
+      type: object
+      additionalProperties:
+        type: object
+        additionalProperties:
+          $ref: "#/components/schemas/ConfigValue"
+      example:
+        Drive A Settings:
+          Drive: Enabled
+          Drive Bus ID: 8
+    ConfigStoreListResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
           properties:
-            data:
-              oneOf:
-                - type: string
-                  description: Base64 encoded bytes.
-                - type: array
-                  items:
-                    type: integer
-                    format: int32
-                    minimum: 0
-                    maximum: 255
-    MemoryDebugResponse:
+            loaded:
+              type: array
+              items:
+                type: string
+            written:
+              type: array
+              items:
+                type: string
+            reset:
+              type: array
+              items:
+                type: string
+    ActionResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
-          required:
-            - value
-          properties:
-            value:
-              type: string
-              description: Hex string read from $D7FF.
+          additionalProperties: true
+    DriveInfo:
+      type: object
+      properties:
+        enabled:
+          type: boolean
+        bus_id:
+          type: integer
+        type:
+          type: string
+        rom:
+          type: string
+        image_file:
+          type: string
+        image_path:
+          type: string
+        last_error:
+          type: string
+        partitions:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              path:
+                type: string
+      additionalProperties: true
     DriveListResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
+          required: [drives]
           properties:
             drives:
               type: array
               items:
                 type: object
                 additionalProperties:
-                  type: object
-                  properties:
-                    enabled:
-                      type: boolean
-                    bus_id:
-                      type: integer
-                    type:
-                      type: string
-                    rom:
-                      type: string
-                    image_file:
-                      type: string
-                    image_path:
-                      type: string
-                    last_error:
-                      type: string
-                    partitions:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          id:
-                            type: integer
-                          path:
-                            type: string
+                  $ref: "#/components/schemas/DriveInfo"
     FileInfoResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
+        - $ref: "#/components/schemas/ErrorList"
         - type: object
+          required: [files]
           properties:
             files:
               type: object
@@ -155,956 +311,1156 @@ components:
                 extension:
                   type: string
               additionalProperties: true
-    MachineActionResponse:
+    InputStateResponse:
       allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-    RunnerActionResponse:
-      allOf:
-        - $ref: '#/components/schemas/ErrorResponse'
-security:
-  - NetworkPassword: []
+        - $ref: "#/components/schemas/ErrorList"
+        - type: object
+          required: [keyboard, joysticks]
+          properties:
+            keyboard:
+              type: object
+              required: [inputs]
+              properties:
+                inputs:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/KeyboardInput"
+            joysticks:
+              type: array
+              items:
+                type: object
+                required: [port, inputs]
+                properties:
+                  port:
+                    type: integer
+                    enum: [1, 2]
+                  inputs:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/JoystickInput"
+    InputBatch:
+      type: object
+      required: [events]
+      properties:
+        events:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items:
+            oneOf:
+              - $ref: "#/components/schemas/KeyboardEvent"
+              - $ref: "#/components/schemas/JoystickEvent"
+              - $ref: "#/components/schemas/ReleaseAllEvent"
+    KeyboardEvent:
+      type: object
+      required: [kind, inputs, transition]
+      properties:
+        kind:
+          const: keyboard
+        inputs:
+          type: array
+          minItems: 1
+          maxItems: 8
+          items:
+            $ref: "#/components/schemas/KeyboardInput"
+        transition:
+          $ref: "#/components/schemas/InputTransition"
+      additionalProperties: false
+    JoystickEvent:
+      type: object
+      required: [kind, port, inputs, transition]
+      properties:
+        kind:
+          const: joystick
+        port:
+          type: integer
+          enum: [1, 2]
+        inputs:
+          type: array
+          minItems: 1
+          maxItems: 7
+          items:
+            $ref: "#/components/schemas/JoystickInput"
+        transition:
+          $ref: "#/components/schemas/InputTransition"
+      additionalProperties: false
+    ReleaseAllEvent:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          const: release_all
+      additionalProperties: false
+    InputTransition:
+      type: string
+      enum: [press, release, tap]
+    KeyboardInput:
+      type: string
+      enum:
+        - inst_del
+        - return
+        - cursor_left_right
+        - f7
+        - f1
+        - f3
+        - f5
+        - cursor_up_down
+        - "0"
+        - "1"
+        - "2"
+        - "3"
+        - "4"
+        - "5"
+        - "6"
+        - "7"
+        - "8"
+        - "9"
+        - a
+        - b
+        - c
+        - d
+        - e
+        - f
+        - g
+        - h
+        - i
+        - j
+        - k
+        - l
+        - m
+        - n
+        - o
+        - p
+        - q
+        - r
+        - s
+        - t
+        - u
+        - v
+        - w
+        - x
+        - y
+        - z
+        - left_shift
+        - right_shift
+        - plus
+        - minus
+        - period
+        - colon
+        - at
+        - comma
+        - pound
+        - star
+        - semicolon
+        - clr_home
+        - equals
+        - arrow_up
+        - slash
+        - arrow_left
+        - ctrl
+        - space
+        - commodore
+        - run_stop
+        - restore
+    JoystickInput:
+      type: string
+      enum: [up, down, left, right, fire, fire2, fire3]
+  requestBodies:
+    BinaryUpload:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            type: object
+            required: [file]
+            properties:
+              file:
+                type: string
+                format: binary
+        application/octet-stream:
+          schema:
+            type: string
+            format: binary
+    SidUpload:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            type: object
+            required: [file]
+            properties:
+              file:
+                type: array
+                minItems: 1
+                maxItems: 2
+                items:
+                  type: string
+                  format: binary
+                description: First file is the SID; optional second file is SID song-length data.
+  responses:
+    JsonOk:
+      description: Successful JSON response.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ActionResponse"
+    BadRequest:
+      description: Request could not be parsed or failed validation.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    Forbidden:
+      description: Network password is configured and `X-Password` is missing or wrong.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    NotFound:
+      description: Route, file, category, item, or active menu screen was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    PreconditionFailed:
+      description: Required request body was missing.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    NotImplemented:
+      description: Firmware route exists, but the current FPGA or hardware capability is unavailable.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
+    ServerError:
+      description: Device-side operation failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorList"
 paths:
+  /v1/help:
+    get:
+      tags: [System]
+      operationId: getHelp
+      summary: Return minimal HTML help for a command.
+      parameters:
+        - name: command
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: HTML help.
+          content:
+            text/html:
+              schema:
+                type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/version:
     get:
-      summary: Get API version
-      description: Returns the firmware-defined REST API semantic version.
+      tags: [System]
+      operationId: getApiVersion
+      summary: Get REST API version.
       responses:
-        '200':
-          description: Successful response
+        "200":
+          description: API version.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/VersionResponse'
-              examples:
-                live:
-                  value:
-                    version: "0.1"
-                    errors: []
+                $ref: "#/components/schemas/VersionResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/info:
     get:
-      summary: Get device information
-      description: >-
-        Returns hardware metadata (product, firmware version, FPGA/core
-        versions, hostname). Available on Ultimate firmware 3.12 and newer. On
-        earlier releases the endpoint responds with HTTP 404.
+      tags: [System]
+      operationId: getDeviceInfo
+      summary: Get device identity and firmware versions.
       responses:
-        '200':
-          description: Successful response
+        "200":
+          description: Device information.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/InfoResponse'
-              examples:
-                live:
-                  value:
-                    product: Ultimate 64 Elite
-                    firmware_version: "3.12a"
-                    fpga_version: "121"
-                    core_version: "1.45"
-                    hostname: c64u
-                    unique_id: 38C1BA
-                    errors: []
+                $ref: "#/components/schemas/InfoResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/runners:sidplay:
     put:
-      summary: Play SID from filesystem
+      tags: [Runners]
+      operationId: playSidFromFile
+      summary: Play a SID file already present on the device filesystem.
       parameters:
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: songnr
-          schema:
-            type: integer
-            minimum: 0
+        - $ref: "#/components/parameters/FileQuery"
+        - $ref: "#/components/parameters/SongNumber"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
-      summary: Play uploaded SID
+      tags: [Runners]
+      operationId: playUploadedSid
+      summary: Upload and play a SID file.
       parameters:
-        - in: query
-          name: songnr
-          schema:
-            type: integer
-            minimum: 0
+        - $ref: "#/components/parameters/SongNumber"
       requestBody:
-        required: true
-        content:
-          multipart/form-data:
-            schema:
-              type: object
-              properties:
-                sid:
-                  type: string
-                  format: binary
-                songlengths:
-                  type: string
-                  format: binary
-              required:
-                - sid
+        $ref: "#/components/requestBodies/SidUpload"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/runners:modplay:
     put:
-      summary: Play MOD from filesystem
+      tags: [Runners]
+      operationId: playModFromFile
+      summary: Play a MOD file from the device filesystem.
+      description: Requires the FPGA sampler capability.
       parameters:
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FileQuery"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
     post:
-      summary: Play uploaded MOD
+      tags: [Runners]
+      operationId: playUploadedMod
+      summary: Upload and play a MOD file.
+      description: Requires the FPGA sampler capability.
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
   /v1/runners:load_prg:
     put:
-      summary: Load PRG from filesystem
+      tags: [Runners]
+      operationId: loadPrgFromFile
+      summary: Load a PRG from the device filesystem without starting it.
       parameters:
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FileQuery"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
-      summary: Load uploaded PRG
+      tags: [Runners]
+      operationId: loadUploadedPrg
+      summary: Upload a PRG and load it without starting it.
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/runners:run_prg:
     put:
-      summary: Run PRG from filesystem
+      tags: [Runners]
+      operationId: runPrgFromFile
+      summary: Load and run a PRG from the device filesystem.
       parameters:
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FileQuery"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
-      summary: Run uploaded PRG
+      tags: [Runners]
+      operationId: runUploadedPrg
+      summary: Upload, load, and run a PRG.
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/runners:run_crt:
     put:
-      summary: Run cartridge from filesystem
+      tags: [Runners]
+      operationId: runCrtFromFile
+      summary: Load and start a CRT cartridge image from the device filesystem.
       parameters:
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FileQuery"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
-      summary: Run uploaded cartridge
+      tags: [Runners]
+      operationId: runUploadedCrt
+      summary: Upload, load, and start a CRT cartridge image.
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Request accepted
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RunnerActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/configs:
     get:
-      summary: List configuration categories
-      description: Enumerates top-level configuration pages as displayed in the
-        Ultimate menu. Supports wildcard queries via URL encoding.
+      tags: [Configuration]
+      operationId: listConfigCategories
+      summary: List configuration categories.
       responses:
-        '200':
-          description: Categories returned
+        "200":
+          description: Configuration categories.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ConfigListResponse'
-              examples:
-                live:
-                  value:
-                    categories:
-                      - Audio Mixer
-                      - SID Sockets Configuration
-                      - UltiSID Configuration
-                      - SID Addressing
-                      - U64 Specific Settings
-                      - C64 and Cartridge Settings
-                      - Clock Settings
-                      - Network Settings
-                      - Ethernet Settings
-                      - WiFi settings
-                      - LED Strip Settings
-                      - Data Streams
-                      - SoftIEC Drive Settings
-                      - Printer Settings
-                      - Modem Settings
-                      - User Interface Settings
-                      - Tape Settings
-                      - Drive A Settings
-                      - Drive B Settings
-                    errors: []
+                $ref: "#/components/schemas/ConfigCategoriesResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     post:
-      summary: Batch update configuration
+      tags: [Configuration]
+      operationId: batchUpdateConfig
+      summary: Apply a JSON batch of configuration values.
+      description: Use single-item `PUT` for interactive writes; batch POST buffers the body on-device.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              additionalProperties:
-                type: object
+              $ref: "#/components/schemas/ConfigBatchUpdate"
       responses:
-        '200':
-          description: Update applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/configs/{category}:
     get:
-      summary: Inspect category
-      description: Returns all items inside the specified category. Wildcards
-        may match multiple categories; each appears as an object property in the
-        response.
+      tags: [Configuration]
+      operationId: getConfigCategory
+      summary: Get matching configuration categories and their current values.
       parameters:
-        - in: path
-          name: category
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Category"
       responses:
-        '200':
-          description: Category returned
+        "200":
+          description: Matching category values.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ConfigCategoryResponse'
-              examples:
-                drive_a:
-                  summary: Drive A Settings (firmware 3.12a)
-                  value:
-                    Drive A Settings:
-                      Drive: Enabled
-                      Drive Type: "1541"
-                      Drive Bus ID: 8
-                      ROM for 1541 mode: 1541.rom
-                      ROM for 1571 mode: 1571.rom
-                      ROM for 1581 mode: 1581.rom
-                      Extra RAM: Disabled
-                      Disk swap delay: 1
-                      Resets when C64 resets: "Yes"
-                      Freezes in menu: "Yes"
-                      GCR Save Align Tracks: "Yes"
-                      Leave Menu on Mount: "Yes"
-                      D64 Geos Copy Protection: none
-                    errors: []
+                $ref: "#/components/schemas/ConfigCategoryResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/configs/{category}/{item}:
     get:
-      summary: Inspect configuration item
+      tags: [Configuration]
+      operationId: getConfigItem
+      summary: Get detailed metadata for matching configuration items.
       parameters:
-        - in: path
-          name: category
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: item
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Category"
+        - $ref: "#/components/parameters/Item"
       responses:
-        '200':
-          description: Item returned
+        "200":
+          description: Matching item metadata.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ConfigItemResponse'
+                $ref: "#/components/schemas/ConfigCategoryResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     put:
-      summary: Update configuration item
+      tags: [Configuration]
+      operationId: updateConfigItem
+      summary: Update one configuration item using the `value` query parameter.
       parameters:
-        - in: path
-          name: category
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: item
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: value
+        - $ref: "#/components/parameters/Category"
+        - $ref: "#/components/parameters/Item"
+        - name: value
+          in: query
           required: true
           schema:
             type: string
       responses:
-        '200':
-          description: Update applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/configs/{category}/{item}/{setting}:
+    put:
+      tags: [Configuration]
+      operationId: updateConfigItemByPath
+      summary: Update one configuration item using the third path segment as the value.
+      parameters:
+        - $ref: "#/components/parameters/Category"
+        - $ref: "#/components/parameters/Item"
+        - $ref: "#/components/parameters/Setting"
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/configs:load_from_flash:
     put:
-      summary: Load configuration from flash
+      tags: [Configuration]
+      operationId: loadAllConfigsFromFlash
+      summary: Reload all configuration stores from flash.
       responses:
-        '200':
-          description: Loaded
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/configs/{category}:load_from_flash:
+    put:
+      tags: [Configuration]
+      operationId: loadConfigCategoryFromFlash
+      summary: Reload matching configuration stores from flash.
+      parameters:
+        - $ref: "#/components/parameters/Category"
+      responses:
+        "200":
+          description: Matching stores loaded.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                $ref: "#/components/schemas/ConfigStoreListResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/configs:save_to_flash:
     put:
-      summary: Save configuration to flash
+      tags: [Configuration]
+      operationId: saveAllConfigsToFlash
+      summary: Save stale configuration stores to flash.
       responses:
-        '200':
-          description: Saved
+        "200":
+          description: Stores written.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-  /v1/configs:reset_to_default:
+                $ref: "#/components/schemas/ConfigStoreListResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/configs/{category}:save_to_flash:
     put:
-      summary: Reset configuration to defaults
+      tags: [Configuration]
+      operationId: saveConfigCategoryToFlash
+      summary: Save matching stale configuration stores to flash.
+      parameters:
+        - $ref: "#/components/parameters/Category"
       responses:
-        '200':
-          description: Reset complete
+        "200":
+          description: Matching stores written.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
-  /v1/machine:reset:
+                $ref: "#/components/schemas/ConfigStoreListResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/configs:reset_to_default:
+    put:
+      tags: [Configuration]
+      operationId: resetAllConfigsToDefault
+      summary: Reset all configuration stores to firmware defaults.
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/configs/{category}:reset_to_default:
     put:
-      summary: Soft reset machine
+      tags: [Configuration]
+      operationId: resetConfigCategoryToDefault
+      summary: Reset matching configuration stores to firmware defaults.
+      parameters:
+        - $ref: "#/components/parameters/Category"
       responses:
-        '200':
-          description: Reset triggered
+        "200":
+          description: Matching stores reset.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+                $ref: "#/components/schemas/ConfigStoreListResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/machine:reset:
+    put:
+      tags: [Machine]
+      operationId: resetMachine
+      summary: Reset the C64.
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:reboot:
     put:
-      summary: Reboot machine
+      tags: [Machine]
+      operationId: rebootMachine
+      summary: Reboot the C64.
       responses:
-        '200':
-          description: Reboot triggered
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:pause:
     put:
-      summary: Pause machine via DMA
+      tags: [Machine]
+      operationId: pauseMachine
+      summary: Pause the machine using DMA.
       responses:
-        '200':
-          description: Pause applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:resume:
     put:
-      summary: Resume machine from pause
+      tags: [Machine]
+      operationId: resumeMachine
+      summary: Resume a paused machine.
       responses:
-        '200':
-          description: Resume applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:poweroff:
     put:
-      summary: Power off machine
+      tags: [Machine]
+      operationId: powerOffMachine
+      summary: Request machine power off.
       responses:
-        '200':
-          description: Power off requested
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:menu_button:
     put:
-      summary: Toggle Ultimate menu button
+      tags: [Machine]
+      operationId: pressMenuButton
+      summary: Press the Ultimate menu button.
       responses:
-        '200':
-          description: Button event queued
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/machine:writemem:
     put:
-      summary: Write memory via query data
+      tags: [Machine]
+      operationId: writeMemoryHex
+      summary: Write up to 128 bytes of C64 memory from a hex string.
       parameters:
-        - in: query
-          name: address
-          required: true
-          schema:
-            type: string
-          description: Hexadecimal start address.
-        - in: query
-          name: data
+        - $ref: "#/components/parameters/Address"
+        - name: data
+          in: query
           required: true
           schema:
             type: string
-          description: Hex string representing bytes (≤ 128 bytes).
+            pattern: "^([0-9A-Fa-f]{2}){1,128}$"
       responses:
-        '200':
-          description: Write applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     post:
-      summary: Write memory via binary payload
+      tags: [Machine]
+      operationId: writeMemoryUpload
+      summary: Write C64 memory from an uploaded binary payload.
       parameters:
-        - in: query
-          name: address
-          required: true
-          schema:
-            type: string
-          description: Hexadecimal start address.
+        - $ref: "#/components/parameters/Address"
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Write applied
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MachineActionResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /v1/machine:readmem:
     get:
-      summary: Read memory
-      description: Performs a DMA read at the requested address. Firmware
-        returns either a JSON wrapper or raw bytes. Use `length` to limit the
-        transfer (default 256 bytes).
+      tags: [Machine]
+      operationId: readMemory
+      summary: Read C64 memory as raw bytes.
       parameters:
-        - in: query
-          name: address
-          required: true
-          schema:
-            type: string
-            description: Hexadecimal start address.
-        - in: query
-          name: length
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 4096
+        - $ref: "#/components/parameters/Address"
+        - $ref: "#/components/parameters/Length"
       responses:
-        '200':
-          description: Memory data
+        "200":
+          description: Raw memory bytes.
           content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MemoryReadJson'
             application/octet-stream:
               schema:
                 type: string
                 format: binary
-              examples:
-                vic_border:
-                  summary: Raw bytes for $D020-$D021
-                  value: !!binary |
-                    /vY=
-  /v1/machine:debugreg:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/machine:menu_screen:
     get:
-      summary: Read debug register
+      tags: [Machine]
+      operationId: readMenuScreen
+      summary: Read the active Ultimate menu screen matrix as raw bytes.
+      description: Returns 404 JSON when no active menu screen matrix is available.
       responses:
-        '200':
-          description: Register value
+        "200":
+          description: Active screen matrix bytes.
           content:
-            application/json:
+            application/octet-stream:
               schema:
-                $ref: '#/components/schemas/MemoryDebugResponse'
+                type: string
+                format: binary
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/machine:debugreg:
+    get:
+      tags: [Machine]
+      operationId: readDebugRegister
+      summary: Read the Ultimate 64 debug register.
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     put:
-      summary: Write debug register
+      tags: [Machine]
+      operationId: writeDebugRegister
+      summary: Write the Ultimate 64 debug register.
       parameters:
-        - in: query
-          name: value
+        - name: value
+          in: query
           required: true
           schema:
             type: string
-            description: Hexadecimal value to write.
+            pattern: "^(0x)?[0-9A-Fa-f]{1,2}$"
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/machine:measure:
+    get:
+      tags: [Machine]
+      operationId: measureCartridgeBus
+      summary: Capture cartridge-bus timing as a VCD file.
+      responses:
+        "200":
+          description: VCD timing capture.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /v1/machine:input:
+    get:
+      tags: [Input]
+      operationId: getInputState
+      summary: Read REST-injected keyboard and joystick state.
       responses:
-        '200':
-          description: Updated register value
+        "200":
+          description: Current input state.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MemoryDebugResponse'
+                $ref: "#/components/schemas/InputStateResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+    post:
+      tags: [Input]
+      operationId: sendInputEvents
+      summary: Apply keyboard and joystick input events.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InputBatch"
+      responses:
+        "200":
+          description: Updated input state.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InputStateResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
+        "500":
+          $ref: "#/components/responses/ServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
   /v1/drives:
     get:
-      summary: List internal drives
-      description: Returns current Ultimate-managed drives, images, and service
-        devices (SoftIEC, printer emulation).
+      tags: [Drives]
+      operationId: listDrives
+      summary: List internal drives and IEC service devices.
       responses:
-        '200':
-          description: Drive information
+        "200":
+          description: Drive list.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DriveListResponse'
-              examples:
-                live:
-                  value:
-                    drives:
-                      - a:
-                          enabled: true
-                          bus_id: 8
-                          type: "1541"
-                          rom: "1541.rom"
-                          image_file: ""
-                          image_path: ""
-                      - b:
-                          enabled: false
-                          bus_id: 9
-                          type: "1541"
-                          rom: "1541.rom"
-                          image_file: ""
-                          image_path: ""
-                      - IEC Drive:
-                          bus_id: 11
-                          enabled: false
-                          type: "DOS emulation"
-                          last_error: "73,U64IEC ULTIMATE DOS V1.1,00,00"
-                          partitions:
-                            - id: 0
-                              path: "/Usb0/"
-                      - Printer Emulation:
-                          bus_id: 4
-                          enabled: false
-                    errors: []
+                $ref: "#/components/schemas/DriveListResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/drives/{drive}:mount:
     put:
-      summary: Mount disk image from filesystem
+      tags: [Drives]
+      operationId: mountDiskImage
+      summary: Mount a disk image from the device filesystem.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: image
+        - $ref: "#/components/parameters/Drive"
+        - name: image
+          in: query
           required: true
           schema:
             type: string
-        - in: query
-          name: type
+        - name: type
+          in: query
+          required: false
           schema:
             type: string
             enum: [d64, g64, d71, g71, d81]
-        - in: query
-          name: mode
+        - name: mode
+          in: query
+          required: false
           schema:
             type: string
             enum: [readwrite, readonly, unlinked]
       responses:
-        '200':
-          description: Mount complete
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     post:
-      summary: Mount uploaded disk image
+      tags: [Drives]
+      operationId: mountUploadedDiskImage
+      summary: Upload and mount a disk image.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: type
+        - $ref: "#/components/parameters/Drive"
+        - name: type
+          in: query
+          required: false
           schema:
             type: string
             enum: [d64, g64, d71, g71, d81]
-        - in: query
-          name: mode
+        - name: mode
+          in: query
+          required: false
           schema:
             type: string
             enum: [readwrite, readonly, unlinked]
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: Mount complete
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/drives/{drive}:reset:
     put:
-      summary: Reset drive
+      tags: [Drives]
+      operationId: resetDrive
+      summary: Reset a drive.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
       responses:
-        '200':
-          description: Reset complete
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/drives/{drive}:remove:
     put:
-      summary: Remove mounted image
+      tags: [Drives]
+      operationId: removeMountedImage
+      summary: Remove the mounted image from a drive.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
       responses:
-        '200':
-          description: Removal complete
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/drives/{drive}:on:
     put:
-      summary: Power on drive
+      tags: [Drives]
+      operationId: powerOnDrive
+      summary: Power on a drive.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
       responses:
-        '200':
-          description: Drive powered on
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/drives/{drive}:off:
     put:
-      summary: Power off drive
+      tags: [Drives]
+      operationId: powerOffDrive
+      summary: Power off a drive.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
       responses:
-        '200':
-          description: Drive powered off
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/drives/{drive}:unlink:
+    put:
+      tags: [Drives]
+      operationId: unlinkMountedImage
+      summary: Unlink the mounted image from host storage.
+      parameters:
+        - $ref: "#/components/parameters/Drive"
+      responses:
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/drives/{drive}:load_rom:
     put:
-      summary: Load ROM from filesystem
+      tags: [Drives]
+      operationId: loadDriveRomFromFile
+      summary: Load a drive ROM from the device filesystem.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: file
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
+        - $ref: "#/components/parameters/FileQuery"
       responses:
-        '200':
-          description: ROM loaded
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
     post:
-      summary: Load ROM from upload
+      tags: [Drives]
+      operationId: loadUploadedDriveRom
+      summary: Upload and load a drive ROM.
       parameters:
-        - in: path
-          name: drive
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/Drive"
       requestBody:
-        required: true
-        content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
+        $ref: "#/components/requestBodies/BinaryUpload"
       responses:
-        '200':
-          description: ROM loaded
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "412":
+          $ref: "#/components/responses/PreconditionFailed"
   /v1/drives/{drive}:set_mode:
     put:
-      summary: Set drive mode
+      tags: [Drives]
+      operationId: setDriveMode
+      summary: Set drive emulation mode.
       parameters:
-        - in: path
-          name: drive
+        - $ref: "#/components/parameters/Drive"
+        - name: mode
+          in: query
           required: true
           schema:
             type: string
-        - in: query
-          name: mode
-          required: true
-          schema:
-            type: string
-            enum: [1541, 1571, 1581]
+            enum: ["1541", "1571", "1581"]
       responses:
-        '200':
-          description: Mode updated
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/streams/{stream}:start:
     put:
-      summary: Start data stream
+      tags: [Streams]
+      operationId: startDataStream
+      summary: Start a data stream.
       parameters:
-        - in: path
-          name: stream
+        - name: stream
+          in: path
           required: true
           schema:
             type: string
             enum: [video, audio, debug]
-        - in: query
-          name: ip
+        - name: ip
+          in: query
           required: true
           schema:
             type: string
-          description: Target IP address with optional port (ip[:port]).
+          description: Destination IPv4 address, optionally with port.
       responses:
-        '200':
-          description: Stream started
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/streams/{stream}:stop:
     put:
-      summary: Stop data stream
+      tags: [Streams]
+      operationId: stopDataStream
+      summary: Stop a data stream.
       parameters:
-        - in: path
-          name: stream
+        - name: stream
+          in: path
           required: true
           schema:
             type: string
             enum: [video, audio, debug]
       responses:
-        '200':
-          description: Stream stopped
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/files/{path}:info:
     get:
-      summary: Inspect file metadata
+      tags: [Files]
+      operationId: getFileInfo
+      summary: Get metadata for a device filesystem path.
       parameters:
-        - in: path
-          name: path
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FilePath"
       responses:
-        '200':
-          description: Metadata returned
+        "200":
+          description: File metadata.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/FileInfoResponse'
-              examples:
-                live:
-                  value:
-                    files:
-                      path: /Flash/roms/1541.rom
-                      filename: 1541.rom
-                      size: 16384
-                      extension: ROM
-                    errors: []
+                $ref: "#/components/schemas/FileInfoResponse"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/files/{path}:create_d64:
     put:
-      summary: Create D64 image
+      tags: [Files]
+      operationId: createD64
+      summary: Create and format a D64 image.
       parameters:
-        - in: path
-          name: path
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: tracks
-          schema:
-            type: integer
-            enum: [35, 40]
-        - in: query
-          name: diskname
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FilePath"
+        - $ref: "#/components/parameters/D64Tracks"
+        - $ref: "#/components/parameters/DiskName"
       responses:
-        '200':
-          description: Image created
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /v1/files/{path}:create_d71:
     put:
-      summary: Create D71 image
+      tags: [Files]
+      operationId: createD71
+      summary: Create and format a D71 image.
       parameters:
-        - in: path
-          name: path
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: diskname
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FilePath"
+        - $ref: "#/components/parameters/DiskName"
       responses:
-        '200':
-          description: Image created
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /v1/files/{path}:create_d81:
     put:
-      summary: Create D81 image
+      tags: [Files]
+      operationId: createD81
+      summary: Create and format a D81 image.
       parameters:
-        - in: path
-          name: path
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: diskname
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FilePath"
+        - $ref: "#/components/parameters/DiskName"
       responses:
-        '200':
-          description: Image created
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /v1/files/{path}:create_dnp:
     put:
-      summary: Create DNP image
+      tags: [Files]
+      operationId: createDnp
+      summary: Create and format a DNP image.
       parameters:
-        - in: path
-          name: path
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: tracks
-          required: true
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 255
-        - in: query
-          name: diskname
-          schema:
-            type: string
+        - $ref: "#/components/parameters/FilePath"
+        - $ref: "#/components/parameters/DnpTracks"
+        - $ref: "#/components/parameters/DiskName"
       responses:
-        '200':
-          description: Image created
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+        "200":
+          $ref: "#/components/responses/JsonOk"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/ServerError"