Spotify Library API

openapi: 3.2.0
info:
  description: You can use Spotify's Web API to discover music and podcasts, manage your Spotify library, control audio playback, and much more.
  version: 1.0.0
  title: Spotify Web Library API
  termsOfService: https://developer.spotify.com/terms/
  contact:
    name: Spotify for Developers Community
    url: https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
servers:
- url: https://api.spotify.com/v1
tags:
- name: Library
paths:
  /me/library:
    put:
      tags:
      - Library
      operationId: save-library-items
      summary: Save Items to Library
      description: Add one or more items to the current user's library. Accepts Spotify URIs for tracks, albums, episodes, shows, audiobooks, users, and playlists.
      parameters:
      - name: uris
        required: true
        in: query
        schema:
          title: Spotify URIs
          description: 'A comma-separated list of [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids). Maximum: 40 URIs.


            Supported URI types:

            - `spotify:track:{id}`

            - `spotify:album:{id}`

            - `spotify:episode:{id}`

            - `spotify:show:{id}`

            - `spotify:audiobook:{id}`

            - `spotify:user:{id}`

            - `spotify:playlist:{id}`

            '
          example: spotify:track:7a3LWj5xSFhFRYmztS8wgK,spotify:album:4aawyAB9vmqN3uQ7FjRGTy
          type: string
      responses:
        '200':
          description: Items saved to library
        '400':
          description: 'Bad Request. Possible reasons: missing `uris` parameter, invalid URI format, unsupported URI type, or more than 40 URIs provided.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-modify
        - user-follow-modify
        - playlist-modify-public
    delete:
      tags:
      - Library
      operationId: remove-library-items
      summary: Remove Items from Library
      description: Remove one or more items from the current user's library. Accepts Spotify URIs for tracks, albums, episodes, shows, audiobooks, users, and playlists.
      parameters:
      - name: uris
        required: true
        in: query
        schema:
          title: Spotify URIs
          description: 'A comma-separated list of [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids). Maximum: 40 URIs.


            Supported URI types:

            - `spotify:track:{id}`

            - `spotify:album:{id}`

            - `spotify:episode:{id}`

            - `spotify:show:{id}`

            - `spotify:audiobook:{id}`

            - `spotify:user:{id}`

            - `spotify:playlist:{id}`

            '
          example: spotify:track:7a3LWj5xSFhFRYmztS8wgK,spotify:album:4aawyAB9vmqN3uQ7FjRGTy
          type: string
      responses:
        '200':
          description: Items removed from library
        '400':
          description: 'Bad Request. Possible reasons: missing `uris` parameter, invalid URI format, unsupported URI type, or more than 40 URIs provided.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-modify
        - user-follow-modify
        - playlist-modify-public
  /me/library/contains:
    get:
      tags:
      - Library
      operationId: check-library-contains
      summary: Check User's Saved Items
      description: Check if one or more items are already saved in the current user's library. Accepts Spotify URIs for tracks, albums, episodes, shows, audiobooks, artists, users, and playlists.
      parameters:
      - name: uris
        required: true
        in: query
        schema:
          title: Spotify URIs
          description: 'A comma-separated list of [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids). Maximum: 40 URIs.


            Supported URI types:

            - `spotify:track:{id}`

            - `spotify:album:{id}`

            - `spotify:episode:{id}`

            - `spotify:show:{id}`

            - `spotify:audiobook:{id}`

            - `spotify:artist:{id}`

            - `spotify:user:{id}`

            - `spotify:playlist:{id}`

            '
          example: spotify:track:7a3LWj5xSFhFRYmztS8wgK,spotify:album:4aawyAB9vmqN3uQ7FjRGTy,spotify:artist:2takcwOaAZWiXQijPHIx7B
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ArrayOfBooleans'
        '400':
          description: 'Bad Request. Possible reasons: missing `uris` parameter, invalid URI format, unsupported URI type, or more than 40 URIs provided.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-read
        - user-follow-read
        - playlist-read-private
components:
  responses:
    Unauthorized:
      description: 'Bad or expired token. This can happen if the user revoked a token or

        the access token has expired. You should re-authenticate the user.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    Forbidden:
      description: 'Bad OAuth request (wrong consumer key, bad nonce, expired

        timestamp...). Unfortunately, re-authenticating the user won''t help here.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    TooManyRequests:
      description: 'The app has exceeded its rate limits.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    ArrayOfBooleans:
      description: Array of booleans
      content:
        application/json:
          schema:
            type: array
            example:
            - false
            - true
            items:
              type: boolean
  schemas:
    ErrorObject:
      type: object
      x-spotify-docs-type: ErrorObject
      required:
      - status
      - message
      properties:
        status:
          type: integer
          minimum: 400
          maximum: 599
          description: 'The HTTP status code (also returned in the response header; see [Response Status Codes](/documentation/web-api/concepts/api-calls#response-status-codes) for more information).

            '
        message:
          type: string
          description: 'A short description of the cause of the error.

            '
  securitySchemes:
    oauth_2_0:
      type: oauth2
      description: Spotify supports OAuth 2.0 for authenticating all API requests.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.spotify.com/authorize
          tokenUrl: https://accounts.spotify.com/api/token
          scopes:
            app-remote-control: 'Communicate with the Spotify app on your device.

              '
            playlist-read-private: 'Access your private playlists.

              '
            playlist-read-collaborative: 'Access your collaborative playlists.

              '
            playlist-modify-public: 'Manage your public playlists.

              '
            playlist-modify-private: 'Manage your private playlists.

              '
            user-library-read: 'Access your saved content.

              '
            user-library-modify: 'Manage your saved content.

              '
            user-read-private: 'Access your subscription details.

              '
            user-read-email: 'Get your real email address.

              '
            user-follow-read: 'Access your followers and who you are following.

              '
            user-follow-modify: 'Manage your saved content.

              '
            user-top-read: 'Read your top artists and content.

              '
            user-read-playback-position: 'Read your position in content you have played.

              '
            user-read-playback-state: 'Read your currently playing content and Spotify Connect devices information.

              '
            user-read-recently-played: 'Access your recently played items.

              '
            user-read-currently-playing: 'Read your currently playing content.

              '
            user-modify-playback-state: 'Control playback on your Spotify clients and Spotify Connect devices.

              '
            ugc-image-upload: 'Upload images to Spotify on your behalf.

              '
            streaming: 'Play content and control playback on your other devices.

              '