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. Starting with DOS 2.14 firmware, the Phantom range (Phantom I, Phantom II, and the Arch and Dialog accessories) exposes device, system, and group state plus playback, volume, equalizer, night-mode, Bluetooth pairing, and power/restart/factory-reset commands over plain HTTP on port 80 under the `/ipcontrol/v1` path prefix. Devices are discovered with mDNS/DNS-SD: they register `_http._tcp` service instances whose TXT record carries `manufacturer=Devialet`, `ipControlVersion=1`, and `path=/ipcontrol/v1`. Queries use GET and are guaranteed not to change device state; commands use POST and require `Content-Type: application/json`. Regular (non-transport) errors are returned inside a `200 OK` response as an `error` object rather than as an HTTP error status.'
  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:
    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'
    BadRequest:
      description: Malformed JSON request. The message body is empty.
    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.
    UnsupportedMediaType:
      description: Invalid or missing `Content-Type` header on a POST request. The only allowed value is `application/json`.
  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:
    EmptyObject:
      type: object
      description: An empty JSON object.
      additionalProperties: false
    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.
    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