Devialet Audio Settings API

openapi: 3.2.0
info:
  title: Devialet IP Control Audio Settings 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: Audio Settings
  description: Equalizer and night-mode settings, hosted by the system leader.
paths:
  /systems/{systemId}/settings/audio/equalizer:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    get:
      operationId: getSystemEqualizer
      tags:
      - Audio Settings
      summary: Get the equalizer configuration
      description: 'Query the equalizer preset, current per-band equalization, stored custom equalization, authorized gain range, and the list of available presets for the designated system. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      responses:
        '200':
          description: The equalizer configuration, or a regular error object.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Equalizer'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                equalizer:
                  summary: From the Devialet reference documentation
                  value:
                    preset: flat
                    currentEqualization:
                      low:
                        frequency: 400
                        gain: 0
                      high:
                        frequency: 2000
                        gain: 0
                    customEqualization:
                      low:
                        gain: -0.5
                      high:
                        gain: 2.25
                    gainRange:
                      min: -6
                      max: 6
                      stepPrecision: 1
                    availablePresets:
                    - flat
                    - custom
                    - voice
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: setSystemEqualizer
      tags:
      - Audio Settings
      summary: Set the equalizer preset and custom gains
      description: 'Select an equalizer preset and optionally update the stored custom per-band gains. Gains are rounded to the nearest authorized multiple of `stepPrecision`; out-of-bounds values report `InvalidValue`. `customEqualization` may be omitted, in which case the stored custom gains are left unchanged. If the system leader is absent, `SystemLeaderAbsent` is reported. If the parameters already match the current state the call succeeds. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EqualizerUpdate'
            examples:
              customPreset:
                summary: Select the custom preset and set gains (Devialet reference documentation)
                value:
                  preset: custom
                  customEqualization:
                    low:
                      gain: 3.0
                    high:
                      gain: 3.0
              flatPreset:
                summary: Select the flat preset (Devialet reference documentation)
                value:
                  preset: flat
      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}/settings/audio/nightMode:
    parameters:
    - $ref: '#/components/parameters/SystemId'
    get:
      operationId: getSystemNightMode
      tags:
      - Audio Settings
      summary: Get the night-mode setting
      description: 'Query the night-mode audio rendering setting for the designated system. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      responses:
        '200':
          description: The night-mode setting, or a regular error object.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NightMode'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                nightMode:
                  summary: From the Devialet reference documentation
                  value:
                    nightMode: 'on'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: setSystemNightMode
      tags:
      - Audio Settings
      summary: Set the night-mode setting
      description: 'Turn night-mode audio rendering on or off for the designated system. If the selection already matches the current state the call succeeds. If the system leader is absent, `SystemLeaderAbsent` is reported. Minimal firmware: DOS >= 2.16.'
      x-devialet-minimal-firmware: DOS >= 2.16
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NightMode'
            examples:
              true:
                summary: From the Devialet reference documentation
                value:
                  nightMode: 'on'
      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:
  schemas:
    EqualizationBand:
      type: object
      description: Per-band equalization. Band labels vary by system; documented examples are `low` and `high`.
      required:
      - gain
      properties:
        frequency:
          type: integer
          description: User-facing central frequency for the band, in hertz. May be rounded, and may be absent.
        gain:
          type: number
          description: Positive or negative gain for the band, in steps. May be fractional.
    NightMode:
      type: object
      description: The night-mode audio rendering selection.
      required:
      - nightMode
      properties:
        nightMode:
          type: string
          enum:
          - 'on'
          - 'off'
          description: Night-mode selection.
    EqualizerUpdate:
      type: object
      description: Equalizer change request. `enabled`, `currentEqualization`, `gainRange`, and `availablePresets` are GET-only and are ignored if sent.
      properties:
        preset:
          type: string
          enum:
          - flat
          - custom
          - voice
          description: The equalizer preset to select.
        customEqualization:
          type: object
          description: Optional. Stored gains for the `custom` preset, keyed by band label. Bands may be sent together (applied simultaneously) or one by one. Omitting this leaves the stored custom gains unchanged.
          additionalProperties:
            $ref: '#/components/schemas/CustomEqualizationBand'
    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.
    CustomEqualizationBand:
      type: object
      description: Per-band gain stored for the `custom` preset.
      required:
      - gain
      properties:
        gain:
          type: number
          description: Positive or negative gain in steps. Rounded by the device to the nearest multiple of `gainRange.stepPrecision`; out-of-bounds values report `InvalidValue`.
    Equalizer:
      type: object
      description: The equalizer configuration of a system.
      properties:
        enabled:
          type: boolean
          description: Read-only. Indicates whether the equalizer is currently active. It can be inactive in certain audio processing modes, in which case settings can still be changed but have no audible effect.
        preset:
          type: string
          description: The selected equalizer preset.
          enum:
          - flat
          - custom
          - voice
        currentEqualization:
          type: object
          description: Gains and frequencies for all bands under the currently selected preset, keyed by band label.
          additionalProperties:
            $ref: '#/components/schemas/EqualizationBand'
        customEqualization:
          type: object
          description: Stored gains for all bands under the `custom` preset, keyed by band label. These can be modified at any time, independently of the selected preset.
          additionalProperties:
            $ref: '#/components/schemas/CustomEqualizationBand'
        gainRange:
          type: object
          description: The authorized gain range and rounding precision for the `custom` preset.
          properties:
            min:
              type: number
              description: Minimal authorized gain, in steps. Applies to all bands.
            max:
              type: number
              description: Maximal authorized gain, in steps. Applies to all bands.
            stepPrecision:
              type: number
              description: Rounding precision, in arbitrary units. Gains are rounded to the nearest multiple. Typical values are 0.1, 0.25, 0.5, and 1.
        availablePresets:
          type: array
          description: The full list of equalizer presets available on this system.
          items:
            type: string
  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.
  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