Dentsply Sirona Devices API

openapi: 3.2.0
info:
  title: Dentsply Sirona Intraoral Modality Devices API
  description: This API is used for acquisition and control of Intraoral sensors. The Devices section provides methods for retrieving information about available intraoral devices (i.e., USB or WiFi interfaces). The Acquisition section provides methods for acquisition of images from a device.
  version: '1.0'
servers:
- url: https://localhost:43809/api/dsio/modality/v1
  description: Default endpoint for local Sensor Plugin service
security:
- BasicAuth: []
tags:
- name: Devices
  description: The device management API provides methods to retrieve information, such as names, icons and status for devices.
paths:
  /devices:
    get:
      tags:
      - Devices
      operationId: getAllDevices
      summary: Get All Devices
      description: Returns a list of the devices that this service currently provides.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceInfo'
  /devices/subscribe:
    get:
      tags:
      - Devices
      operationId: subscribeDevices
      summary: Subscribe to Device Events
      description: 'Subscribe to changes in the Device list using Server Sent Events (EventSource). The API service will send this event when a device is added, removed or changed. The event data consists of a `DeviceInfo` object indicating the device that was affected. API consumers can update their own list accordingly, or retrieve an updated list of devices using the `GET /devices` method.


        The service will send a periodic heartbeat message in order to keep the connection active. The frequency of the heartbeat can be controlled by the optional query parameter, heartbeat.'
      parameters:
      - name: heartbeat
        in: query
        description: An optional parameter specifying the desired heartbeat interval in ms.  A value of 0 will disable the heartbeat.
        required: false
        schema:
          type: number
          default: 20000
          minimum: 1000
          maximum: 60000
      responses:
        '200':
          description: Subscription started
          content:
            text/event-stream:
              schema:
                type: object
                format: chunked
                properties:
                  event:
                    type: string
                    enum:
                    - message
                    - heartbeat
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/DeviceEventData'
                    - $ref: '#/components/schemas/Heartbeat'
                example: 'event: heartbeat

                  data: { "heartbeatTimeout": 20000 }


                  event: message

                  data: { "action":"changed","deviceInfo":{"deviceId":"bc91c079-dabe-0170-1c5e-6ee92b3f4a35","name":"Schick 33: 213402981","iconUrl":"http://example.com/api/devices/bc91c079-dabe-0170-1c5e-6ee92b3f4a35/icon.png","hasSensor":false,"status":"Available","interfaceType":"usb","modelName":"Schick AE USB Interface","serialNumber":"34-05921813233","version":"1.2","battery":null} }

                  '
  /devices/{deviceId}:
    get:
      tags:
      - Devices
      operationId: getDeviceInfo
      summary: Get Device Information
      description: Returns information about a device.
      parameters:
      - name: deviceId
        in: path
        description: The Id of the device
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInfo'
        '404':
          description: Device not found
  /devices/{deviceId}/sensor:
    get:
      tags:
      - Devices
      operationId: getSensorInfo
      summary: Get Sensor Information
      description: Returns information about the currently connected sensor. An empty response indicates no sensor connected.
      parameters:
      - name: deviceId
        in: path
        description: The Id of the device
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorInfo'
        '404':
          description: Device not found
components:
  schemas:
    BatteryInfo:
      description: Contains information about the current state of the battery in the device if applicable.
      type: object
      properties:
        hasBattery:
          description: Flag indicating if the device is battery powered
          type: boolean
          example: true
        percentRemaining:
          description: A number in the range 0-100 indicating the percentage of battery power remaining
          type: number
          format: float
          example: 78.0
        level:
          description: "A coarse description of the battery power level. May be used to update a color scheme in the user interface \n  * `Low` - The battery is low and should be recharged\n  * `Good` - The battery level is sufficient\n  * `Full` - The battery was recently recharged\n"
          type: string
          enum:
          - Low
          - Good
          - Full
          example: Good
    Heartbeat:
      description: Contains the timeout interval for a heartbeat message sent to subscribed clients.
      type: object
      properties:
        heartbeatTimeout:
          description: The heartbeat timeout interval in ms.
          type: number
          example: 1000
    SensorInfo:
      description: Detailed information about an intraoral sensor.
      type: object
      properties:
        modelName:
          description: Manufacturer's model name of the sensor
          type: string
          example: Schick 33
        serialNumber:
          description: Serial number of sensor
          type: string
          example: 213402981
        brand:
          description: Branding information of sensor
          type: string
          example: Schick
        family:
          description: Product family of sensor
          type: string
          example: Supreme
        size:
          description: Sensor size
          type: number
          enum:
          - 0
          - 1
          - 2
          example: 2
        width:
          description: Width of sensor in pixels
          type: number
          example: 2400
        height:
          description: Height of sensor in pixels
          type: number
          example: 1708
        supportsBinning:
          description: Flag indicating if the sensor supports Binning (see `AcquisitionInfo`)
          type: boolean
        version:
          description: Version of software running on the sensor
          type: string
          example: 0.15
    DeviceInfo:
      description: Detailed information about an intraoral device (sensor interface)
      type: object
      properties:
        deviceId:
          description: Unique Id of the device
          type: string
          example: bc91c079-dabe-0170-1c5e-6ee92b3f4a35
        name:
          description: Descriptive name of the device
          type: string
          example: 'Schick 33: 213402981'
        iconUrl:
          description: Url for an icon representing the device
          type: string
          example: http://example.com/api/devices/bc91c079-dabe-0170-1c5e-6ee92b3f4a35/icon.png
        hasSensor:
          description: Flag indicating if a sensor is connected to this device
          type: boolean
        status:
          $ref: '#/components/schemas/DeviceStatus'
        interfaceType:
          description: The interface used to connect the device to the system. For example, a USB device may report *usb*, while a network based device may report *network*.
          type: string
          example: usb
        modelName:
          description: Manufacturer's model name
          type: string
          example: Schick AE USB Interface
        serialNumber:
          description: Serial number of the device
          type: string
          example: 34-05921813233
        version:
          description: Version of software running on the device
          type: string
          example: 1.2
        battery:
          $ref: '#/components/schemas/BatteryInfo'
    DeviceStatus:
      description: "Describes the current status of the device:\n  * `Available` - Device is available for an acquisition\n  * `InUse` - Device is currently being used for an acquisition\n  * `Unavailable` - Device is not available at this time\n  * `Error` Device encountered an unspecified error\n  \n  The current status must be `Available` in order to use it for an acquisition. If the device status returns `InUse`, it indicates that the device is currently being used for an acquisition.\n"
      type: string
      enum:
      - Available
      - InUse
      - Unavailable
      - Error
      example: Available
    DeviceEventData:
      description: Describes changes to the list of devices including added, removed and changed devices. A device may change if a different sensor is connected causing the name and icon to be modified or when a device is used for a session causing the status to be modified.
      type: object
      properties:
        data:
          type: object
          properties:
            action:
              type: string
              enum:
              - added
              - removed
              - changed
              example: changed
            deviceInfo:
              $ref: '#/components/schemas/DeviceInfo'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic