Devialet Sound Control API

openapi: 3.2.0
info:
  title: Devialet IP Control Sound Control 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: Sound Control
  description: Volume query and control at the system level.
paths:
  /systems/{systemId}/sources/current/soundControl/volume:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    get:
      operationId: getSystemVolume
      tags:
      - Sound Control
      summary: Get the current system volume
      description: 'Query the current volume of the designated system, in percent (0-100). All devices in the same system share the same volume. Minimal firmware: DOS >= 2.14.'
      x-devialet-minimal-firmware: DOS >= 2.14
      responses:
        '200':
          description: The current volume, or a regular error object.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Volume'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                volume:
                  summary: From the Devialet reference documentation
                  value:
                    volume: 35
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: setSystemVolume
      tags:
      - Sound Control
      summary: Set the system volume
      description: 'Set the current volume of the designated system, in percent (0-100). All volume commands unmute the current source but do not change `playingState`. Values outside the range report the `InvalidValue` error code. Minimal firmware: DOS >= 2.14.'
      x-devialet-minimal-firmware: DOS >= 2.14
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Volume'
            examples:
              volume:
                summary: From the Devialet reference documentation
                value:
                  volume: 35
      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}/sources/current/soundControl/volumeUp:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: systemVolumeUp
      tags:
      - Sound Control
      summary: Increase the system volume by one step
      description: 'Increase the volume of the designated system by one non-configurable step of 5% of the volume range. If the current volume is closer to 100% than the step, it is set to 100%; if it is already 100% the request still succeeds. Minimal firmware: DOS >= 2.14.'
      x-devialet-minimal-firmware: DOS >= 2.14
      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}/sources/current/soundControl/volumeDown:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    post:
      operationId: systemVolumeDown
      tags:
      - Sound Control
      summary: Decrease the system volume by one step
      description: 'Decrease the volume of the designated system by one non-configurable step of 5% of the volume range. If the current volume is closer to 0% than the step, it is set to 0%; if it is already 0% the request still succeeds. Minimal firmware: DOS >= 2.14.'
      x-devialet-minimal-firmware: DOS >= 2.14
      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:
  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: {}
  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.
  schemas:
    Volume:
      type: object
      description: The volume of a system, in percent.
      required:
      - volume
      properties:
        volume:
          type: integer
          minimum: 0
          maximum: 100
          description: Current volume of the system, in percent.
    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:
    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