openapi.yaml

openapi: 3.1.0
info:
  title: Sony Camera Control Local Plugin API
  version: 1.0.0
  description: >-
    Versioned local API for camera capability discovery, property control,
    capture, downloaded photos, JPEG live view, focus, recording, and events.
    The contract is vendor-neutral even though the current adapter uses Sony
    Camera Remote SDK.
servers:
  - url: http://127.0.0.1:8080/api/v1
    description: Default local server
security:
  - bearerAuth: []
  - tokenHeader: []
  - {}
paths:
  /:
    get:
      summary: Get API identity and documentation links
      security: []
      responses:
        '200':
          description: API information
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiInfo' }
  /discovery:
    post:
      summary: Start or reuse an asynchronous camera-discovery job
      x-permission: admin
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                timeoutSeconds: { type: integer, minimum: 1, maximum: 10, default: 2 }
                preferCache: { type: boolean, default: false }
      responses:
        '202':
          description: Discovery job accepted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiscoveryJob' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
    get:
      summary: Get the latest discovery state
      x-permission: admin
      responses:
        '200':
          description: Latest discovery state
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiscoveryJob' }
        '404': { $ref: '#/components/responses/NotFound' }
  /discovery/{jobId}:
    parameters:
      - name: jobId
        in: path
        required: true
        schema: { type: integer, minimum: 1 }
    get:
      summary: Poll one asynchronous discovery job
      x-permission: admin
      responses:
        '200':
          description: Discovery state
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiscoveryJob' }
        '404': { $ref: '#/components/responses/NotFound' }
  /cameras:
    get:
      summary: Enumerate the primary camera and camera-pool sessions
      x-permission: monitor
      responses:
        '200':
          description: Current camera selectors and status
          content:
            application/json:
              schema:
                type: object
                required: [ok, apiVersion, cameras]
                properties:
                  ok: { const: true }
                  apiVersion: { type: string }
                  recommendedCameraId: { type: string }
                  cameras:
                    type: array
                    items: { $ref: '#/components/schemas/Camera' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /cameras/{cameraId}:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    get:
      summary: Get one camera's current status
      x-permission: monitor
      responses:
        '200':
          description: Camera state
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { const: true }
                  apiVersion: { type: string }
                  selector: { type: string }
                  cameraId: { type: string }
                  label: { type: string }
                  status: { $ref: '#/components/schemas/CameraStatus' }
        '404': { $ref: '#/components/responses/NotFound' }
  /cameras/{cameraId}/capabilities:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    get:
      summary: Inspect protocol features and runtime camera properties
      x-permission: monitor
      responses:
        '200':
          description: Feature and property capabilities
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { const: true }
                  apiVersion: { type: string }
                  cameraId: { type: string }
                  features: { type: object, additionalProperties: true }
                  featureStates: { type: object, additionalProperties: true }
                  status: { $ref: '#/components/schemas/CameraStatus' }
                  properties: { $ref: '#/components/schemas/PropertyList' }
  /cameras/{cameraId}/actions/connect:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Establish a Remote control session from discovery or IPv4 address
      x-permission: admin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ConnectionRequest' }
      responses:
        '200': { description: Control session connected or already connected }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /cameras/{cameraId}/actions/reconnect:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Reconnect using the camera's saved in-memory connection recipe
      x-permission: admin
      responses:
        '200': { description: Camera was already connected }
        '202': { description: Reconnect accepted }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/disconnect:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Disconnect the selected camera session
      x-permission: admin
      responses:
        '200': { description: Camera disconnected }
  /cameras/{cameraId}/properties:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    get:
      summary: List runtime properties supported in the current camera state
      x-permission: monitor
      responses:
        '200':
          description: Property list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PropertyList' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/properties/{propertyName}:
    parameters:
      - $ref: '#/components/parameters/CameraId'
      - name: propertyName
        in: path
        required: true
        schema: { type: string, pattern: '^[A-Za-z0-9_-]+$' }
    get:
      summary: Read one property
      x-permission: monitor
      responses:
        '200':
          description: Property
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CameraProperty' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
    put:
      summary: Set one property to a value advertised by possibleValues
      x-permission: control
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PropertyWrite' }
          application/x-www-form-urlencoded:
            schema: { $ref: '#/components/schemas/PropertyWrite' }
      responses:
        '200':
          description: Updated property
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/live-view/frame:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    get:
      summary: Get one live-view JPEG frame
      x-permission: monitor
      responses:
        '200':
          description: JPEG monitor frame
          headers:
            X-CamRemote-Camera-Id: { schema: { type: string } }
          content:
            image/jpeg:
              schema: { type: string, contentEncoding: binary }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/Unavailable' }
  /cameras/{cameraId}/live-view/stream:
    parameters:
      - $ref: '#/components/parameters/CameraId'
      - name: fps
        in: query
        schema: { type: integer, minimum: 1, maximum: 30, default: 10 }
    get:
      summary: Open an MJPEG live-view stream
      x-permission: monitor
      responses:
        '200':
          description: Multipart JPEG stream
          content:
            multipart/x-mixed-replace:
              schema: { type: string, contentEncoding: binary }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/capture:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Trigger a still capture and optionally wait for file transfer
      x-permission: capture
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                waitMs: { type: integer, minimum: 0, maximum: 30000, default: 0 }
      responses:
        '200':
          description: Capture accepted and photo returned before timeout
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CaptureResult' }
        '202':
          description: Capture accepted; photo is still asynchronous
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CaptureResult' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/focus:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Autofocus, optionally at a 640 x 480 touch-grid point
      x-permission: control
      requestBody:
        content:
          application/json:
            schema:
              type: object
              dependentRequired: { x: [y], y: [x] }
              properties:
                x: { type: integer, minimum: 0, maximum: 639 }
                y: { type: integer, minimum: 0, maximum: 479 }
      responses:
        '200': { description: Focus command completed }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/clear-focus:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Clear the remote touch focus point
      x-permission: control
      responses:
        '200': { description: Focus point cleared }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/capture-mode:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Switch between still and movie modes
      x-permission: control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mode]
              properties:
                mode: { type: string, enum: [photo, video] }
      responses:
        '200': { description: Mode selected }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/actions/recording:
    parameters:
      - $ref: '#/components/parameters/CameraId'
    post:
      summary: Start, stop, or toggle movie recording
      x-permission: control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action: { type: string, enum: [start, stop, toggle] }
      responses:
        '200': { description: Recording state confirmed }
        '400': { $ref: '#/components/responses/BadRequest' }
        '409': { $ref: '#/components/responses/Conflict' }
  /cameras/{cameraId}/photos:
    parameters:
      - $ref: '#/components/parameters/CameraId'
      - name: since
        in: query
        description: Include files modified at or after this Unix millisecond timestamp
        schema: { type: integer, minimum: 0, default: 0 }
      - name: limit
        in: query
        schema: { type: integer, minimum: 1, maximum: 1000, default: 100 }
    get:
      summary: List downloaded photos scoped to one camera
      x-permission: capture
      responses:
        '200':
          description: Newest-first photo list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PhotoList' }
  /cameras/{cameraId}/photos/content:
    parameters:
      - $ref: '#/components/parameters/CameraId'
      - name: name
        in: query
        required: true
        schema: { type: string }
    get:
      summary: Download one photo by scoped relative name
      x-permission: capture
      responses:
        '200':
          description: Photo bytes
          content:
            image/jpeg: { schema: { type: string, contentEncoding: binary } }
            image/png: { schema: { type: string, contentEncoding: binary } }
            image/heif: { schema: { type: string, contentEncoding: binary } }
            application/octet-stream: { schema: { type: string, contentEncoding: binary } }
        '404': { $ref: '#/components/responses/NotFound' }
  /cameras/{cameraId}/events:
    parameters:
      - $ref: '#/components/parameters/CameraId'
      - name: after
        in: query
        schema: { type: integer, minimum: 0, default: 0 }
      - name: timeoutMs
        in: query
        schema: { type: integer, minimum: 0, maximum: 30000, default: 0 }
    get:
      summary: Long-poll camera state and media revision
      x-permission: monitor
      responses:
        '200':
          description: Current revision and latest state
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EventState' }
  /docs:
    get:
      summary: Get English API documentation
      security: []
      responses:
        '200': { description: Markdown documentation }
  /docs/zh-CN:
    get:
      summary: Get Simplified Chinese API documentation
      security: []
      responses:
        '200': { description: Markdown documentation }
  /openapi.yaml:
    get:
      summary: Get this OpenAPI contract
      security: []
      responses:
        '200': { description: OpenAPI YAML }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    tokenHeader:
      type: apiKey
      in: header
      name: X-CamRemote-Token
  parameters:
    CameraId:
      name: cameraId
      in: path
      required: true
      description: active, primary, or a runtime cam-* selector returned by /cameras
      schema: { type: string, pattern: '^[A-Za-z0-9_-]+$' }
  schemas:
    ApiInfo:
      type: object
      required: [ok, name, apiVersion]
      properties:
        ok: { const: true }
        name: { type: string }
        apiVersion: { type: string }
        vendorNeutral: { type: boolean }
        cameraSelectors: { type: array, items: { type: string } }
        serviceDiscovery:
          type: object
          properties:
            schemaVersion: { type: integer }
            jsonFile: { type: string }
            registry: { type: string }
        documentation: { type: object, additionalProperties: { type: string } }
    Camera:
      type: object
      required: [id, label, role, status]
      properties:
        id: { type: string }
        label: { type: string }
        role: { type: string, enum: [primary, pool] }
        projects: { type: array, items: { type: string } }
        status: { $ref: '#/components/schemas/CameraStatus' }
    CameraStatus:
      type: object
      additionalProperties: true
      properties:
        initialized: { type: boolean }
        connected: { type: boolean }
        controlAvailable: { type: boolean }
        controlSessionState: { type: string, enum: [ready, reconnecting, storage_mode, disconnected] }
        controlUnavailableReason: { type: string }
        propertiesAvailable: { type: boolean }
        liveViewAvailable: { type: boolean }
        mediaLibraryAvailable: { type: boolean }
        authenticationRequired: { type: boolean }
        fileOnlyMode: { type: boolean }
        connectionState: { type: string }
        recording: { type: boolean }
        model: { type: string }
        transport: { type: string }
        lastError: { type: string }
        liveViewError: { type: string }
        lastDownload: { type: string }
    DiscoveryCamera:
      type: object
      properties:
        index: { type: integer, minimum: 0 }
        model: { type: string }
        id: { type: string }
        connectionType: { type: string }
        transport: { type: string }
        requiresAuthentication: { type: boolean }
        fingerprint: { type: string }
    DiscoveryState:
      type: object
      properties:
        jobId: { type: integer }
        scanning: { type: boolean }
        complete: { type: boolean }
        found: { type: integer }
        discoveredButNotConnected: { type: boolean }
        authenticationRequired: { type: boolean }
        cameras:
          type: array
          items: { $ref: '#/components/schemas/DiscoveryCamera' }
    DiscoveryJob:
      type: object
      properties:
        ok: { const: true }
        apiVersion: { type: string }
        jobId: { type: integer }
        statusUrl: { type: string }
        discovery: { $ref: '#/components/schemas/DiscoveryState' }
    ConnectionRequest:
      type: object
      properties:
        index: { type: integer, minimum: 0 }
        ip: { type: string, format: ipv4 }
        transport: { type: string, enum: [network, usb] }
        user: { type: string }
        password: { type: string, writeOnly: true }
      oneOf:
        - required: [index]
        - required: [ip]
    PropertyList:
      type: object
      required: [properties]
      properties:
        properties:
          type: array
          items: { $ref: '#/components/schemas/CameraProperty' }
    CameraProperty:
      type: object
      additionalProperties: true
      properties:
        name: { type: string }
        label: { type: string }
        value:
          oneOf: [{ type: integer }, { type: string }]
        formatted: { type: string }
        settable: { type: boolean }
        possibleValues:
          type: array
          items:
            oneOf: [{ type: integer }, { type: string }]
    PropertyWrite:
      type: object
      required: [value]
      properties:
        value:
          description: Unsigned decimal number or 0x-prefixed hexadecimal string
          oneOf: [{ type: integer, minimum: 0 }, { type: string }]
    CaptureResult:
      type: object
      required: [ok, apiVersion, cameraId, accepted]
      properties:
        ok: { const: true }
        apiVersion: { type: string }
        cameraId: { type: string }
        accepted: { type: boolean }
        photo:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PhotoReference'
    PhotoReference:
      type: object
      properties:
        name: { type: string }
        contentUrl: { type: string }
    PhotoList:
      type: object
      properties:
        ok: { const: true }
        apiVersion: { type: string }
        cameraId: { type: string }
        photos:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/PhotoReference'
              - type: object
                properties:
                  size: { type: integer }
                  modified: { type: integer }
                  previewable: { type: boolean }
    EventState:
      type: object
      properties:
        ok: { const: true }
        apiVersion: { type: string }
        cameraId: { type: string }
        changed: { type: boolean }
        revision: { type: integer }
        lastDownload: { type: string }
        status: { $ref: '#/components/schemas/CameraStatus' }
    Error:
      type: object
      required: [ok, apiVersion, error]
      properties:
        ok: { const: false }
        apiVersion: { type: string }
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }
  responses:
    BadRequest:
      description: Invalid request value
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }
    Unauthorized:
      description: Missing or invalid access token
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }
    Forbidden:
      description: Token lacks permission or origin check failed
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }
    NotFound:
      description: Resource not found
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }
    Conflict:
      description: Camera state or capability rejected the command
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }
    Unavailable:
      description: Camera resource is temporarily unavailable
      content:
        application/json: { schema: { $ref: '#/components/schemas/Error' } }