Devialet Devices API

openapi: 3.2.0
info:
  title: Devialet IP Control Devices API
  version: '1'
  summary: Local-network HTTP control API for Devialet Phantom speakers and accessories.
  description: The Devialet IP Control API is an unauthenticated HTTP API served by Devialet devices themselves on the local network.
  x-provenance:
    method: derived
    generated: '2026-08-04'
    derived_from: openapi/_original/devialet-ip-control-r1.pdf
    source_document: Devialet IP Control — REFERENCE API DOCUMENTATION, Revision 1, December 2021
    source_url: https://help.devialet.com/hc/en-us/articles/4415207423378-Phantom-s-documentation-for-piloting-them-via-IP
    attachment_url: https://help.devialet.com/hc/en-us/article_attachments/4415236063506
    note: Devialet publishes this API as a PDF reference document, not as a machine-readable specification. This OpenAPI is an API Evangelist derivation that transcribes only what the Revision 1 reference document specifies. It is not published or endorsed by Devialet. Endpoints that the reference mentions in passing but does not specify (`/devices/{deviceId}/identify`, `/groups/{groupId}/sources/current/soundControl/volume`, `/groups/{groupId}/sources/current/playback/position`) are deliberately omitted here and recorded in conventions/devialet-conventions.yml instead.
  contact:
    name: Devialet Help Center
    url: https://help.devialet.com/
  license:
    name: © 2021 Devialet. All rights reserved.
    url: https://www.devialet.com/en-eu/legal/
servers:
- url: http://{deviceAddress}/ipcontrol/v1
  description: A Devialet device on the local network. `deviceAddress` is the IPv4 or IPv6 address (or mDNS hostname) of any reachable Devialet device — that device becomes the "dispatcher" and forwards commands to the rest of the installation. The default below is the example address used in Devialet's reference documentation.
  variables:
    deviceAddress:
      default: 192.168.1.20
      description: IP address or mDNS hostname of a Devialet device on the local network.
tags:
- name: Devices
  description: Individual physical Devialet products on the local network, including accessories.
paths:
  /devices/{deviceId}:
    parameters:
    - $ref: '#/components/parameters/DeviceId'
    get:
      operationId: getDevice
      tags:
      - Devices
      summary: Get device information
      description: 'Query general information pertaining to the designated device — identifiers, model, firmware version, serial number, role, and device name. Minimal firmware: DOS >= 2.14. Also available as a NOTIFICATION channel in a future revision (subscriptions are not yet implemented).'
      x-devialet-minimal-firmware: DOS >= 2.14
      responses:
        '200':
          description: Device information, or a regular error object.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Device'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                accessory:
                  summary: An Arch accessory (from the Devialet reference documentation)
                  value:
                    deviceId: f42cf307-f5bb-4311-a917-1e06d404f595
                    model: Arch
                    release:
                      version: 2.14.2
                    serial: P35V12345UX02
                    deviceName: '      💿 CD Player'
                speaker:
                  summary: A Phantom II speaker (from the Devialet reference documentation)
                  value:
                    deviceId: 5b35aa24-e4c9-4942-a501-7b0cf5c1e892
                    systemId: 44a53d02-c69f-4a01-a0ce-1b6588b1d5b1
                    groupId: 0e985d77-8212-4b48-842b-9e102d52887e
                    model: Phantom II 98 dB
                    release:
                      version: 2.14.2
                    role: Mono
                    serial: P35V12345TQ9A
                    deviceName: Kitchen
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /devices/{deviceId}/powerOff:
    parameters:
    - $ref: '#/components/parameters/DeviceId'
    post:
      operationId: powerOffDevice
      tags:
      - Devices
      summary: Power off the device
      description: 'Turn off the designated device. Exiting OFF mode is only possible by pressing a physical button on the device. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      requestBody:
        $ref: '#/components/requestBodies/NoParameters'
      responses:
        '200':
          $ref: '#/components/responses/EmptyOrError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
  /devices/{deviceId}/restart:
    parameters:
    - $ref: '#/components/parameters/DeviceId'
    post:
      operationId: restartDevice
      tags:
      - Devices
      summary: Restart the device
      description: 'Reboot the designated device. The device becomes unresponsive during the reboot. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      requestBody:
        $ref: '#/components/requestBodies/NoParameters'
      responses:
        '200':
          $ref: '#/components/responses/EmptyOrError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
  /devices/{deviceId}/resetToFactorySettings:
    parameters:
    - $ref: '#/components/parameters/DeviceId'
    post:
      operationId: resetDeviceToFactorySettings
      tags:
      - Devices
      summary: Reset the device to factory settings
      description: 'Reset the designated device to factory settings and reboot it. This erases all network credentials — unless the device is connected by Ethernet it becomes inaccessible. It does not roll back the firmware version. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      requestBody:
        $ref: '#/components/requestBodies/NoParameters'
      responses:
        '200':
          $ref: '#/components/responses/EmptyOrError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    UnsupportedMediaType:
      description: Invalid or missing `Content-Type` header on a POST request. The only allowed value is `application/json`.
    InternalError:
      description: Unexpected internal error. The body, when present, follows the regular error format, but its content is not part of the officially supported API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    EmptyOrError:
      description: Success (an empty JSON object) or a regular error. Devialet returns regular errors with HTTP status 200 and an `error` object in the body.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/EmptyObject'
            - $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            success:
              summary: Successful command
              value: {}
            regularError:
              summary: Regular error returned with HTTP 200
              value:
                error:
                  code: UnreachableDevices
    NotFound:
      description: Non-existing endpoint — for example a `/systems/...` or `/groups/...` request performed against a non-speaker accessory. The message body is empty.
    BadRequest:
      description: Malformed JSON request. The message body is empty.
  requestBodies:
    NoParameters:
      required: false
      description: 'This command takes no parameters. The body may be empty or an empty JSON object (`{}`), but the `Content-Type: application/json` header is mandatory.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmptyObject'
          examples:
            empty:
              value: {}
  schemas:
    Device:
      type: object
      description: A physically separate Devialet product connected to the local network.
      required:
      - deviceId
      - model
      - release
      - serial
      - deviceName
      properties:
        deviceId:
          type: string
          description: Unique device identifier in UUIDv4 format.
        systemId:
          type: string
          description: Unique identifier of the system the device belongs to, in UUIDv4 format. Present for speakers only — accessories such as Arch or Dialog belong to no system.
        groupId:
          type: string
          description: Unique identifier of the group the device belongs to (via its system), in UUIDv4 format. Present for speakers only.
        model:
          type: string
          description: Human-readable model name. The language is English but non-ASCII characters may be present (for example "Phantom I Opéra de Paris").
        release:
          type: object
          description: Firmware release information.
          required:
          - version
          properties:
            version:
              type: string
              description: Human-readable firmware version, usually MAJOR.MINOR.PATCH but may carry additional non-numerical information. ASCII only.
        serial:
          type: string
          description: Device serial number, usually 13 ASCII characters.
        role:
          type: string
          description: The device's role in its system. Present for speakers only.
          enum:
          - FrontLeft
          - FrontRight
          - Mono
        deviceName:
          type: string
          description: Human-readable non-empty UTF-8 name, typically describing the physical location of the speaker system or the source device of an accessory.
    EmptyObject:
      type: object
      description: An empty JSON object.
      additionalProperties: false
    ErrorEnvelope:
      type: object
      description: The regular error envelope. Returned with HTTP status 200 for application-level errors, and with 500 for unexpected internal errors.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          properties:
            code:
              type: string
              description: A predefined error identifier. Unknown codes must be handled gracefully by the client and shown as a generic error message.
              examples:
              - Error
              - UnreachableDevices
              - Timeout
              - NoCurrentSource
              - InvalidValue
            details:
              type: object
              description: Structured data whose shape depends on the error identifier, for building a localized user-facing message.
              additionalProperties: true
            message:
              type: string
              description: Debug-only text. Not intended for display to end users or for programmatic processing.
  parameters:
    DeviceId:
      name: deviceId
      in: path
      required: true
      description: Device identifier. The only value supported today is `current`, which refers to the dispatcher — the device that received the request.
      schema:
        type: string
        default: current
        examples:
        - current