Spotify Web API — Player

naftiko: 1.0.0-alpha2
info:
  label: Spotify Web API — Player
  description: 'Spotify Web API — Player. 15 operations. Lead operation: Get Playback State. Self-contained Naftiko capability
    covering one Spotify business surface.'
  tags:
  - Spotify
  - Player
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SPOTIFY_API_KEY: SPOTIFY_API_KEY
capability:
  consumes:
  - type: http
    namespace: spotify-player
    baseUri: https://api.spotify.com/v1
    description: Spotify Web API — Player business capability. Self-contained, no shared references.
    resources:
    - name: me-player
      path: /me/player
      operations:
      - name: getinformationabouttheuserscurrentplayback
        method: GET
        description: Get Playback State
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: transferausersplayback
        method: PUT
        description: Transfer Playback
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: me-player-currently-playing
      path: /me/player/currently-playing
      operations:
      - name: gettheuserscurrentlyplayingtrack
        method: GET
        description: Get Currently Playing Track
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: me-player-devices
      path: /me/player/devices
      operations:
      - name: getausersavailabledevices
        method: GET
        description: Get Available Devices
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: me-player-next
      path: /me/player/next
      operations:
      - name: skipusersplaybacktonexttrack
        method: POST
        description: Skip To Next
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: device_id
          in: query
          type: string
    - name: me-player-pause
      path: /me/player/pause
      operations:
      - name: pauseausersplayback
        method: PUT
        description: Pause Playback
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: device_id
          in: query
          type: string
    - name: me-player-play
      path: /me/player/play
      operations:
      - name: startausersplayback
        method: PUT
        description: Start/Resume Playback
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: device_id
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: me-player-previous
      path: /me/player/previous
      operations:
      - name: skipusersplaybacktoprevioustrack
        method: POST
        description: Skip To Previous
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: device_id
          in: query
          type: string
    - name: me-player-queue
      path: /me/player/queue
      operations:
      - name: getqueue
        method: GET
        description: Get the User's Queue
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: addtoqueue
        method: POST
        description: Add Item to Playback Queue
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: uri
          in: query
          type: string
          required: true
        - name: device_id
          in: query
          type: string
    - name: me-player-recently-played
      path: /me/player/recently-played
      operations:
      - name: getrecentlyplayed
        method: GET
        description: Get Recently Played Tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
        - name: after
          in: query
          type: integer
        - name: before
          in: query
          type: integer
    - name: me-player-repeat
      path: /me/player/repeat
      operations:
      - name: setrepeatmodeonusersplayback
        method: PUT
        description: Set Repeat Mode
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: state
          in: query
          type: string
          required: true
        - name: device_id
          in: query
          type: string
    - name: me-player-seek
      path: /me/player/seek
      operations:
      - name: seektopositionincurrentlyplayingtrack
        method: PUT
        description: Seek To Position
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: position_ms
          in: query
          type: integer
          required: true
        - name: device_id
          in: query
          type: string
    - name: me-player-shuffle
      path: /me/player/shuffle
      operations:
      - name: toggleshuffleforusersplayback
        method: PUT
        description: Toggle Playback Shuffle
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: state
          in: query
          type: boolean
          required: true
        - name: device_id
          in: query
          type: string
    - name: me-player-volume
      path: /me/player/volume
      operations:
      - name: setvolumeforusersplayback
        method: PUT
        description: Set Playback Volume
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: volume_percent
          in: query
          type: integer
          required: true
        - name: device_id
          in: query
          type: string
    authentication:
      type: bearer
      token: '{{env.SPOTIFY_API_KEY}}'
  exposes:
  - type: rest
    namespace: spotify-player-rest
    port: 8080
    description: REST adapter for Spotify Web API — Player. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/me/player
      name: me-player
      description: REST surface for me-player.
      operations:
      - method: GET
        name: getinformationabouttheuserscurrentplayback
        description: Get Playback State
        call: spotify-player.getinformationabouttheuserscurrentplayback
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: transferausersplayback
        description: Transfer Playback
        call: spotify-player.transferausersplayback
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/currently-playing
      name: me-player-currently-playing
      description: REST surface for me-player-currently-playing.
      operations:
      - method: GET
        name: gettheuserscurrentlyplayingtrack
        description: Get Currently Playing Track
        call: spotify-player.gettheuserscurrentlyplayingtrack
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/devices
      name: me-player-devices
      description: REST surface for me-player-devices.
      operations:
      - method: GET
        name: getausersavailabledevices
        description: Get Available Devices
        call: spotify-player.getausersavailabledevices
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/next
      name: me-player-next
      description: REST surface for me-player-next.
      operations:
      - method: POST
        name: skipusersplaybacktonexttrack
        description: Skip To Next
        call: spotify-player.skipusersplaybacktonexttrack
        with:
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/pause
      name: me-player-pause
      description: REST surface for me-player-pause.
      operations:
      - method: PUT
        name: pauseausersplayback
        description: Pause Playback
        call: spotify-player.pauseausersplayback
        with:
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/play
      name: me-player-play
      description: REST surface for me-player-play.
      operations:
      - method: PUT
        name: startausersplayback
        description: Start/Resume Playback
        call: spotify-player.startausersplayback
        with:
          device_id: rest.device_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/previous
      name: me-player-previous
      description: REST surface for me-player-previous.
      operations:
      - method: POST
        name: skipusersplaybacktoprevioustrack
        description: Skip To Previous
        call: spotify-player.skipusersplaybacktoprevioustrack
        with:
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/queue
      name: me-player-queue
      description: REST surface for me-player-queue.
      operations:
      - method: GET
        name: getqueue
        description: Get the User's Queue
        call: spotify-player.getqueue
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: addtoqueue
        description: Add Item to Playback Queue
        call: spotify-player.addtoqueue
        with:
          uri: rest.uri
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/recently-played
      name: me-player-recently-played
      description: REST surface for me-player-recently-played.
      operations:
      - method: GET
        name: getrecentlyplayed
        description: Get Recently Played Tracks
        call: spotify-player.getrecentlyplayed
        with:
          limit: rest.limit
          after: rest.after
          before: rest.before
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/repeat
      name: me-player-repeat
      description: REST surface for me-player-repeat.
      operations:
      - method: PUT
        name: setrepeatmodeonusersplayback
        description: Set Repeat Mode
        call: spotify-player.setrepeatmodeonusersplayback
        with:
          state: rest.state
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/seek
      name: me-player-seek
      description: REST surface for me-player-seek.
      operations:
      - method: PUT
        name: seektopositionincurrentlyplayingtrack
        description: Seek To Position
        call: spotify-player.seektopositionincurrentlyplayingtrack
        with:
          position_ms: rest.position_ms
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/shuffle
      name: me-player-shuffle
      description: REST surface for me-player-shuffle.
      operations:
      - method: PUT
        name: toggleshuffleforusersplayback
        description: Toggle Playback Shuffle
        call: spotify-player.toggleshuffleforusersplayback
        with:
          state: rest.state
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/player/volume
      name: me-player-volume
      description: REST surface for me-player-volume.
      operations:
      - method: PUT
        name: setvolumeforusersplayback
        description: Set Playback Volume
        call: spotify-player.setvolumeforusersplayback
        with:
          volume_percent: rest.volume_percent
          device_id: rest.device_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: spotify-player-mcp
    port: 9090
    transport: http
    description: MCP adapter for Spotify Web API — Player. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: get-playback-state
      description: Get Playback State
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-player.getinformationabouttheuserscurrentplayback
      outputParameters:
      - type: object
        mapping: $.
    - name: transfer-playback
      description: Transfer Playback
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.transferausersplayback
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-currently-playing-track
      description: Get Currently Playing Track
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-player.gettheuserscurrentlyplayingtrack
      outputParameters:
      - type: object
        mapping: $.
    - name: get-available-devices
      description: Get Available Devices
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-player.getausersavailabledevices
      outputParameters:
      - type: object
        mapping: $.
    - name: skip-next
      description: Skip To Next
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: spotify-player.skipusersplaybacktonexttrack
      with:
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: pause-playback
      description: Pause Playback
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.pauseausersplayback
      with:
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: start-resume-playback
      description: Start/Resume Playback
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.startausersplayback
      with:
        device_id: tools.device_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: skip-previous
      description: Skip To Previous
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: spotify-player.skipusersplaybacktoprevioustrack
      with:
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user-s-queue
      description: Get the User's Queue
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-player.getqueue
      outputParameters:
      - type: object
        mapping: $.
    - name: add-item-playback-queue
      description: Add Item to Playback Queue
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: spotify-player.addtoqueue
      with:
        uri: tools.uri
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-recently-played-tracks
      description: Get Recently Played Tracks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-player.getrecentlyplayed
      with:
        limit: tools.limit
        after: tools.after
        before: tools.before
      outputParameters:
      - type: object
        mapping: $.
    - name: set-repeat-mode
      description: Set Repeat Mode
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.setrepeatmodeonusersplayback
      with:
        state: tools.state
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: seek-position
      description: Seek To Position
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.seektopositionincurrentlyplayingtrack
      with:
        position_ms: tools.position_ms
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: toggle-playback-shuffle
      description: Toggle Playback Shuffle
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.toggleshuffleforusersplayback
      with:
        state: tools.state
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.
    - name: set-playback-volume
      description: Set Playback Volume
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-player.setvolumeforusersplayback
      with:
        volume_percent: tools.volume_percent
        device_id: tools.device_id
      outputParameters:
      - type: object
        mapping: $.