Ricoh USA Protocol API

openapi: 3.1.0
info:
  title: RICOH THETA Web Protocol API
  version: 2.1.0
  description: 'HTTP-over-Wi-Fi API for controlling RICOH THETA 360-degree cameras (Z1, X, A1) conforming to the

    Open Spherical Camera (OSC) API Level 2 specification (Google) with Ricoh vendor extensions. The

    camera operates either in access-point mode (default base URL http://192.168.1.1) or as a Wi-Fi

    client. All commands are POST requests to /osc/commands/execute with a JSON body identifying the

    command name and parameters; long-running commands return an in-progress state polled via

    /osc/commands/status.

    '
  contact:
    name: RICOH360 Developer Support
    url: https://link.ricoh360.com/contact
  license:
    name: Documentation under RICOH terms
    url: https://docs-theta-api.ricoh360.com/
  x-source: https://github.com/ricohapi/theta-api-specs/tree/main/theta-web-api-v2.1
servers:
- url: http://192.168.1.1
  description: THETA camera in access-point mode (default)
tags:
- name: Protocol
  description: Core OSC protocol endpoints
paths:
  /osc/info:
    get:
      tags:
      - Protocol
      summary: Get Camera Info
      operationId: getInfo
      description: Returns immutable camera identity, supported API levels, endpoints, and feature flags.
      responses:
        '200':
          description: Camera information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CameraInfo'
  /osc/state:
    post:
      tags:
      - Protocol
      summary: Get Camera State
      operationId: getState
      description: Returns mutable state such as battery level, storage usage, capture status, and fingerprint used for change detection.
      responses:
        '200':
          description: Camera state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CameraState'
  /osc/checkForUpdates:
    post:
      tags:
      - Protocol
      summary: Check For Updates
      operationId: checkForUpdates
      description: Polls the camera with a known state fingerprint and returns the new fingerprint when state changes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - stateFingerprint
              properties:
                stateFingerprint:
                  type: string
                waitTimeout:
                  type: integer
      responses:
        '200':
          description: Updated fingerprint
          content:
            application/json:
              schema:
                type: object
                properties:
                  stateFingerprint:
                    type: string
                  throttleTimeout:
                    type: integer
  /osc/commands/execute:
    post:
      tags:
      - Protocol
      summary: Execute Command
      operationId: executeCommand
      description: Invokes an OSC command by name with a parameters object. Used for all shooting, media, settings, plug-in, and network operations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommandExecuteRequest'
      responses:
        '200':
          description: Command result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandExecuteResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /osc/commands/status:
    post:
      tags:
      - Protocol
      summary: Get Command Status
      operationId: getCommandStatus
      description: Polls the status of a long-running command using the command id returned by /osc/commands/execute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
      responses:
        '200':
          description: Command status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandExecuteResponse'
components:
  schemas:
    CameraInfo:
      type: object
      properties:
        manufacturer:
          type: string
        model:
          type: string
        serialNumber:
          type: string
        firmwareVersion:
          type: string
        supportUrl:
          type: string
        gps:
          type: boolean
        gyro:
          type: boolean
        endpoints:
          type: object
          properties:
            httpPort:
              type: integer
            httpUpdatesPort:
              type: integer
        apiLevel:
          type: array
          items:
            type: integer
        uptime:
          type: integer
        api:
          type: array
          items:
            type: string
        _wlanMacAddress:
          type: string
        _bluetoothMacAddress:
          type: string
    CommandExecuteRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: OSC command name (e.g. camera.takePicture, camera.startCapture)
          examples:
          - camera.takePicture
          - camera.startCapture
          - camera.stopCapture
          - camera.listFiles
          - camera.delete
          - camera.getLivePreview
          - camera.getOptions
          - camera.setOptions
          - camera.reset
          - camera._finishWlan
          - camera._getMetadata
          - camera._getMySetting
          - camera._setMySetting
          - camera._deleteMySetting
          - camera._stopSelfTimer
          - camera._convertVideoFormats
          - camera._cancelVideoConvert
          - camera._setBluetoothDevice
          - camera._listAccessPoints
          - camera._setAccessPoint
          - camera._deleteAccessPoint
          - camera._listPlugins
          - camera._setPlugin
          - camera._pluginControl
          - camera._getPluginLicense
          - camera._getPluginOrders
          - camera._setPluginOrders
        parameters:
          type: object
          additionalProperties: true
    CameraState:
      type: object
      properties:
        fingerprint:
          type: string
        state:
          type: object
          properties:
            batteryLevel:
              type: number
            storageUri:
              type: string
            _captureStatus:
              type: string
              enum:
              - idle
              - shooting
              - self-timer-countdown
              - bracket-shooting
              - converting
              - timeshift-shooting
            _recordedTime:
              type: integer
            _recordableTime:
              type: integer
            _capturedPictures:
              type: integer
            _latestFileUrl:
              type: string
            _batteryState:
              type: string
            _apiVersion:
              type: integer
    Error:
      type: object
      properties:
        code:
          type: string
          description: OSC / Ricoh-specific error code such as missingParameter, invalidParameterName, invalidParameterValue, disabledCommand, cameraInExclusiveUse.
        message:
          type: string
    CommandExecuteResponse:
      type: object
      properties:
        name:
          type: string
        state:
          type: string
          enum:
          - done
          - inProgress
          - error
        id:
          type: string
        results:
          type: object
          additionalProperties: true
        error:
          $ref: '#/components/schemas/Error'
        progress:
          type: object
          properties:
            completion:
              type: number