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. Browse our available Web API endpoints using the sidebar at left, or via the navigation bar on top of this page on smaller screens.


    In order to make successful Web API requests your app will need a valid access token. One can be obtained through <a href="https://developer.spotify.com/documentation/general/guides/authorization-guide/">OAuth 2.0</a>.


    The base URI for all Web API requests is `https://api.spotify.com/v1`.


    Need help? See our <a href="https://developer.spotify.com/documentation/web-api/guides/">Web API guides</a> for more information, or visit the <a href="https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer">Spotify for Developers community forum</a> to ask questions and connect with other developers.

    '
  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'
    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
    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'
  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.

              '