Devialet Playback API

openapi: 3.2.0
info:
  title: Devialet IP Control Playback 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: Playback
  description: Play, pause, mute, unmute, next, and previous on the group's current source.
paths:
  /groups/{groupId}/sources/{sourceId}/playback/play:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    - $ref: '#/components/parameters/SourceId'
    post:
      operationId: playGroupSource
      tags:
      - Playback
      summary: Play or resume a source
      description: 'Start or resume playback of the designated source on the group and set its `playingState` to `playing`. If the designated source is not the current source it is selected first and the previous source is paused and unselected. The call may have asynchronous effects — clients should re-read `getGroupCurrentSource` rather than trust the response. If playback cannot start, `PlaybackNoStream` is reported and the source still becomes current with no sound. If the source is already the current, playing source, the call succeeds. Selecting an AirPlay 2 or Roon Ready source removes the host system from its current group. 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'
  /groups/{groupId}/sources/current/playback/pause:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    post:
      operationId: pauseGroupPlayback
      tags:
      - Playback
      summary: Pause the current source
      description: 'Pause playback of the group''s current source and set its `playingState` to `paused`. All sources accept this command; sources that cannot semantically pause (for example `optical`) mute the output instead, leaving `playingState` as `playing` and setting `muteState` to `muted`. If already paused, the call 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'
  /groups/{groupId}/sources/current/playback/mute:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    post:
      operationId: muteGroupPlayback
      tags:
      - Playback
      summary: Mute the current source
      description: 'Mute playback of the group''s current source and set its `muteState` to `muted`. Mute state is independent of play/pause state. If already muted, the call 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'
  /groups/{groupId}/sources/current/playback/unmute:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    post:
      operationId: unmuteGroupPlayback
      tags:
      - Playback
      summary: Unmute the current source
      description: 'Unmute playback of the group''s current source and set its `muteState` to `unmuted`. If already unmuted, the call succeeds. Note that every volume command also unmutes the current source. 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'
  /groups/{groupId}/sources/current/playback/next:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    post:
      operationId: nextGroupTrack
      tags:
      - Playback
      summary: Skip to the next track
      description: 'Start playback of the next track on the group''s current source. If the current source does not offer the next operation, `PlaybackOperationNotAvailable` is reported — check `availableOperations` from `getGroupCurrentSource` first. 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'
  /groups/{groupId}/sources/current/playback/previous:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    post:
      operationId: previousGroupTrack
      tags:
      - Playback
      summary: Skip to the previous track
      description: 'Start playback of the previous track on the group''s current source. If the current source does not offer the previous operation, `PlaybackOperationNotAvailable` is reported. "Restart the current track" behaviour is not supported by this endpoint and must be implemented client-side. 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:
  parameters:
    SourceId:
      name: sourceId
      in: path
      required: true
      description: Source identifier in UUIDv4 format, as returned by `listGroupSources`. An unrecognised value results in a 200 response carrying a regular error object, not a 404.
      schema:
        type: string
        examples:
        - 213a3ed0-1fb9-4da2-bcf4-066da0f7b27e
    GroupId:
      name: groupId
      in: path
      required: true
      description: Group identifier. The only value supported today is `current`, which refers to the group of the dispatcher.
      schema:
        type: string
        default: current
        examples:
        - current
  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'
    UnsupportedMediaType:
      description: Invalid or missing `Content-Type` header on a POST request. The only allowed value is `application/json`.
    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:
    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.