API Evangelist enhancements for the Devialet IP Control API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Devialet IP Control API
  version: 1.0.0
extends: openapi/devialet-ip-control-openapi.yml
x-provenance:
  generated: '2026-08-04'
  method: generated
  source: openapi/_original/devialet-ip-control-r1.pdf
  note: >-
    Devialet publishes no machine-readable specification, so the base document
    openapi/devialet-ip-control-openapi.yml is itself an API Evangelist transcription of Devialet's
    PDF reference. This overlay carries the API Evangelist annotations layered on top of that
    transcription — provenance, agent-facing safety classification, and cross-links to the derived
    artifacts in this repo — so the transcription stays a faithful reading of the source document
    and our editorial additions stay separable from it.
actions:
  - target: $.info
    description: Record provenance and cross-link the derived artifacts in this repository.
    update:
      x-apievangelist-profile: https://apievangelist.com/
      x-apievangelist-artifacts:
        authentication: authentication/devialet-authentication.yml
        errors: errors/devialet-error-codes.yml
        conventions: conventions/devialet-conventions.yml
        lifecycle: lifecycle/devialet-lifecycle.yml
        changelog: changelog/devialet-changelog.yml
        conformance: conformance/devialet-conformance.yml
        data_model: data-model/devialet-data-model.yml
        examples: examples/devialet-ip-control-examples.yml
        packages: packages/devialet-packages.yml
        mcp: mcp/devialet-mcp.yml
        tool_crosswalk: mcp/devialet-tool-crosswalk.yml
        skills: skills/_index.yml
        llms_txt: llms/devialet-llms.txt
      x-apievangelist-source-document: >-
        Devialet IP Control — REFERENCE API DOCUMENTATION, Revision 1, December 2021
      x-apievangelist-authored-by: API Evangelist (not published or endorsed by Devialet)
  - target: $.info
    description: Flag the unauthenticated posture at the document level.
    update:
      x-apievangelist-security-posture:
        authentication: none
        transport: http
        tls: false
        boundary: local network only
        implication: >-
          Any client that can reach the device on the LAN can issue every command, including
          irreversible ones. Network segmentation is the only control.
  - target: $.info
    description: Record the error-handling deviation that most affects client and agent correctness.
    update:
      x-apievangelist-error-model:
        style: envelope-in-200
        warning: >-
          Application errors are returned with HTTP status 200 and an `error` object in the body.
          Testing only the HTTP status will silently treat failures as successes. Clients MUST
          inspect the 200 body for an `error` key.
  - target: $.paths['/devices/{deviceId}/resetToFactorySettings'].post
    description: Mark the irreversible device-level factory reset.
    update:
      x-apievangelist-consequence: irreversible
      x-apievangelist-agent-guidance: >-
        Erases network credentials. On a Wi-Fi-only deployment the device becomes unreachable and
        cannot be recovered over the network. Require explicit human confirmation before calling.
  - target: $.paths['/systems/{systemId}/resetToFactorySettings'].post
    description: Mark the irreversible system-wide factory reset.
    update:
      x-apievangelist-consequence: irreversible
      x-apievangelist-agent-guidance: >-
        Applies to every device in the system. Erases network credentials on all of them. Require
        explicit human confirmation before calling.
  - target: $.paths['/devices/{deviceId}/powerOff'].post
    description: Mark power-off as physically unrecoverable over the network.
    update:
      x-apievangelist-consequence: physical
      x-apievangelist-agent-guidance: >-
        There is no power-on endpoint. Exiting OFF mode requires pressing a physical button on the
        device, so this command cannot be undone remotely.
  - target: $.paths['/systems/{systemId}/powerOff'].post
    description: Mark system power-off as physically unrecoverable over the network.
    update:
      x-apievangelist-consequence: physical
      x-apievangelist-agent-guidance: >-
        There is no power-on endpoint. Every device in the system must be restarted by pressing its
        physical button.
  - target: $.paths['/groups/{groupId}/sources/current/playback/next'].post
    description: Flag the non-idempotent playback advance.
    update:
      x-apievangelist-idempotent: false
      x-apievangelist-agent-guidance: >-
        Advances the playlist. Do not retry blindly after a timeout — re-read
        getGroupCurrentSource first. Check availableOperations before calling at all.
  - target: $.paths['/groups/{groupId}/sources/current/playback/previous'].post
    description: Flag the non-idempotent playback rewind.
    update:
      x-apievangelist-idempotent: false
      x-apievangelist-agent-guidance: >-
        Moves the playlist backwards. Do not retry blindly after a timeout. Check
        availableOperations before calling.
  - target: $.paths['/systems/{systemId}/sources/current/soundControl/volumeUp'].post
    description: Flag the relative volume step as non-idempotent away from the boundary.
    update:
      x-apievangelist-idempotent: false
      x-apievangelist-agent-guidance: >-
        Relative +5% step. Repeat-safe only at 100%. For retry-safe volume changes use
        setSystemVolume with an absolute value.
  - target: $.paths['/systems/{systemId}/sources/current/soundControl/volumeDown'].post
    description: Flag the relative volume step as non-idempotent away from the boundary.
    update:
      x-apievangelist-idempotent: false
      x-apievangelist-agent-guidance: >-
        Relative -5% step. Repeat-safe only at 0%. For retry-safe volume changes use
        setSystemVolume with an absolute value.
  - target: $.paths['/groups/{groupId}/sources/{sourceId}/playback/play'].post
    description: Flag the asynchronous completion semantics.
    update:
      x-apievangelist-async-effects: true
      x-apievangelist-idempotent: true
      x-apievangelist-agent-guidance: >-
        A reported success does not mean playback started. Re-read getGroupCurrentSource and check
        playingState. A delayed failure produces no notification. Selecting an AirPlay 2 or Roon
        Ready source restructures group membership and can change groupId.