Spotify Web API — Users

naftiko: 1.0.0-alpha2
info:
  label: Spotify Web API — Users
  description: 'Spotify Web API — Users. 11 operations. Lead operation: Get Current User''s Profile. Self-contained Naftiko
    capability covering one Spotify business surface.'
  tags:
  - Spotify
  - Users
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SPOTIFY_API_KEY: SPOTIFY_API_KEY
capability:
  consumes:
  - type: http
    namespace: spotify-users
    baseUri: https://api.spotify.com/v1
    description: Spotify Web API — Users business capability. Self-contained, no shared references.
    resources:
    - name: me
      path: /me
      operations:
      - name: getcurrentusersprofile
        method: GET
        description: Get Current User's Profile
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: me-following
      path: /me/following
      operations:
      - name: getfollowed
        method: GET
        description: Get Followed Artists
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: query
          type: string
          required: true
        - name: after
          in: query
          type: string
        - name: limit
          in: query
          type: integer
      - name: followartistsusers
        method: PUT
        description: Follow Artists or Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: query
          type: string
          required: true
        - name: ids
          in: query
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: unfollowartistsusers
        method: DELETE
        description: Unfollow Artists or Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: query
          type: string
          required: true
        - name: ids
          in: query
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: me-following-contains
      path: /me/following/contains
      operations:
      - name: checkcurrentuserfollows
        method: GET
        description: Check If User Follows Artists or Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: query
          type: string
          required: true
        - name: ids
          in: query
          type: string
          required: true
    - name: me-top-type
      path: /me/top/{type}
      operations:
      - name: getuserstopartistsandtracks
        method: GET
        description: Get User's Top Items
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: path
          type: string
          required: true
        - name: time_range
          in: query
          type: string
    - name: playlists-playlist_id-followers
      path: /playlists/{playlist_id}/followers
      operations:
      - name: followplaylist
        method: PUT
        description: Follow Playlist
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: unfollowplaylist
        method: DELETE
        description: Unfollow Playlist
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: playlists-playlist_id-followers-contains
      path: /playlists/{playlist_id}/followers/contains
      operations:
      - name: checkifuserfollowsplaylist
        method: GET
        description: Check if Current User Follows Playlist
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: string
    - name: users-user_id
      path: /users/{user_id}
      operations:
      - name: getusersprofile
        method: GET
        description: Get User's Profile
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-user_id-playlists
      path: /users/{user_id}/playlists
      operations:
      - name: getlistusersplaylists
        method: GET
        description: Get User's Playlists
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: offset
          in: query
          type: integer
    authentication:
      type: bearer
      token: '{{env.SPOTIFY_API_KEY}}'
  exposes:
  - type: rest
    namespace: spotify-users-rest
    port: 8080
    description: REST adapter for Spotify Web API — Users. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/me
      name: me
      description: REST surface for me.
      operations:
      - method: GET
        name: getcurrentusersprofile
        description: Get Current User's Profile
        call: spotify-users.getcurrentusersprofile
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/following
      name: me-following
      description: REST surface for me-following.
      operations:
      - method: GET
        name: getfollowed
        description: Get Followed Artists
        call: spotify-users.getfollowed
        with:
          type: rest.type
          after: rest.after
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: followartistsusers
        description: Follow Artists or Users
        call: spotify-users.followartistsusers
        with:
          type: rest.type
          ids: rest.ids
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: unfollowartistsusers
        description: Unfollow Artists or Users
        call: spotify-users.unfollowartistsusers
        with:
          type: rest.type
          ids: rest.ids
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/following/contains
      name: me-following-contains
      description: REST surface for me-following-contains.
      operations:
      - method: GET
        name: checkcurrentuserfollows
        description: Check If User Follows Artists or Users
        call: spotify-users.checkcurrentuserfollows
        with:
          type: rest.type
          ids: rest.ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/me/top/{type}
      name: me-top-type
      description: REST surface for me-top-type.
      operations:
      - method: GET
        name: getuserstopartistsandtracks
        description: Get User's Top Items
        call: spotify-users.getuserstopartistsandtracks
        with:
          type: rest.type
          time_range: rest.time_range
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/playlists/{playlist-id}/followers
      name: playlists-playlist-id-followers
      description: REST surface for playlists-playlist_id-followers.
      operations:
      - method: PUT
        name: followplaylist
        description: Follow Playlist
        call: spotify-users.followplaylist
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: unfollowplaylist
        description: Unfollow Playlist
        call: spotify-users.unfollowplaylist
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/playlists/{playlist-id}/followers/contains
      name: playlists-playlist-id-followers-contains
      description: REST surface for playlists-playlist_id-followers-contains.
      operations:
      - method: GET
        name: checkifuserfollowsplaylist
        description: Check if Current User Follows Playlist
        call: spotify-users.checkifuserfollowsplaylist
        with:
          ids: rest.ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{user-id}
      name: users-user-id
      description: REST surface for users-user_id.
      operations:
      - method: GET
        name: getusersprofile
        description: Get User's Profile
        call: spotify-users.getusersprofile
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{user-id}/playlists
      name: users-user-id-playlists
      description: REST surface for users-user_id-playlists.
      operations:
      - method: GET
        name: getlistusersplaylists
        description: Get User's Playlists
        call: spotify-users.getlistusersplaylists
        with:
          offset: rest.offset
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: spotify-users-mcp
    port: 9090
    transport: http
    description: MCP adapter for Spotify Web API — Users. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: get-current-user-s-profile
      description: Get Current User's Profile
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.getcurrentusersprofile
      outputParameters:
      - type: object
        mapping: $.
    - name: get-followed-artists
      description: Get Followed Artists
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.getfollowed
      with:
        type: tools.type
        after: tools.after
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: follow-artists-users
      description: Follow Artists or Users
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-users.followartistsusers
      with:
        type: tools.type
        ids: tools.ids
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: unfollow-artists-users
      description: Unfollow Artists or Users
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: spotify-users.unfollowartistsusers
      with:
        type: tools.type
        ids: tools.ids
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: check-if-user-follows-artists
      description: Check If User Follows Artists or Users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.checkcurrentuserfollows
      with:
        type: tools.type
        ids: tools.ids
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user-s-top-items
      description: Get User's Top Items
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.getuserstopartistsandtracks
      with:
        type: tools.type
        time_range: tools.time_range
      outputParameters:
      - type: object
        mapping: $.
    - name: follow-playlist
      description: Follow Playlist
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: spotify-users.followplaylist
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: unfollow-playlist
      description: Unfollow Playlist
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: spotify-users.unfollowplaylist
      outputParameters:
      - type: object
        mapping: $.
    - name: check-if-current-user-follows
      description: Check if Current User Follows Playlist
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.checkifuserfollowsplaylist
      with:
        ids: tools.ids
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user-s-profile
      description: Get User's Profile
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.getusersprofile
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user-s-playlists
      description: Get User's Playlists
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: spotify-users.getlistusersplaylists
      with:
        offset: tools.offset
      outputParameters:
      - type: object
        mapping: $.