Devialet Systems API

openapi: 3.2.0
info:
  title: Devialet IP Control Systems 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: Systems
  description: Sets of one or more speakers that always share playback state (solo or stereo).
paths:
  /systems/{systemId}:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    get:
      operationId: getSystem
      tags:
      - Systems
      summary: Get system information
      description: 'Query general information pertaining to the designated system. For non-speaker accessories such as Dialog or Arch, use `getDevice` instead. Minimal firmware: DOS >= 2.14 (DOS >= 2.16 for `availableFeatures`).'
      x-devialet-minimal-firmware: DOS >= 2.14
      responses:
        '200':
          description: System information, or a regular error object.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/System'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                system:
                  summary: From the Devialet reference documentation
                  value:
                    systemId: 13531594-b1c1-42c7-8d5a-18fa9e5d7cd4
                    groupId: 0e985d77-8212-4b48-842b-9e102d52887e
                    systemName: Dining room 🍴
                    availableFeatures:
                    - equalizer
                    - nightMode
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /systems/{systemId}/bluetooth/startAdvertising:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: startSystemBluetoothAdvertising
      tags:
      - Systems
      summary: Start Bluetooth advertising
      description: 'Make the designated system discoverable for Bluetooth pairing. Advertising turns off automatically after one minute or on a successful Bluetooth connection; re-issuing the command resets the timeout to one minute. If the advertising device cannot be reached by the dispatcher, `UnreachableDevice` is reported. 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'
  /systems/{systemId}/powerOff:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: powerOffSystem
      tags:
      - Systems
      summary: Power off every device in the system
      description: 'Turn off all devices of the designated system. Exiting OFF mode is only possible by pressing a physical button on each 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'
  /systems/{systemId}/restart:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: restartSystem
      tags:
      - Systems
      summary: Restart every device in the system
      description: 'Reboot all devices of the designated system. The devices become 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'
  /systems/{systemId}/resetToFactorySettings:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: resetSystemToFactorySettings
      tags:
      - Systems
      summary: Reset every device in the system to factory settings
      description: 'Reset all devices of the designated system to factory settings and reboot them. This erases all network credentials — unless the devices are connected by Ethernet they become 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:
    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`.
    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
    BadRequest:
      description: Malformed JSON request. The message body is empty.
  schemas:
    EmptyObject:
      type: object
      description: An empty JSON object.
      additionalProperties: false
    System:
      type: object
      description: A set of one or more speakers that always share playback state.
      required:
      - systemId
      - groupId
      - systemName
      properties:
        systemId:
          type: string
          description: Unique system identifier in UUIDv4 format.
        groupId:
          type: string
          description: Unique identifier of the group this system belongs to, in UUIDv4 format.
        systemName:
          type: string
          description: Human-readable non-empty UTF-8 name, typically describing the physical location of the speaker system.
        availableFeatures:
          type: array
          description: Features available on this system. Requires DOS >= 2.16.
          items:
            type: string
            enum:
            - equalizer
            - nightMode
    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:
    SystemId:
      name: systemId
      in: path
      required: true
      description: System identifier. The only value supported today is `current`, which refers to the system of the dispatcher.
      schema:
        type: string
        default: current
        examples:
        - current
  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: {}