openapi: 3.0.3
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 Albums Categories 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: Categories
paths:
  /browse/categories:
    get:
      deprecated: true
      tags:
      - Categories
      operationId: get-categories
      summary: 'Get Several Browse Categories

        '
      description: 'Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

        '
      parameters:
      - name: locale
        required: false
        in: query
        schema:
          title: Locale
          description: 'The desired language, consisting of an [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) language code and an [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), joined by an underscore. For example: `es_MX`, meaning &quot;Spanish (Mexico)&quot;. Provide this parameter if you want the category strings returned in a particular language.<br/> _**Note**: if `locale` is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English)._

            '
          example: sv_SE
          type: string
      - $ref: '#/components/parameters/QueryLimit'
      - $ref: '#/components/parameters/QueryOffset'
      responses:
        '200':
          $ref: '#/components/responses/PagedCategories'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /browse/categories/{category_id}:
    get:
      deprecated: true
      tags:
      - Categories
      operationId: get-a-category
      summary: 'Get Single Browse Category

        '
      description: 'Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

        '
      parameters:
      - name: category_id
        required: true
        in: path
        schema:
          title: Category ID
          description: 'The [Spotify category ID](/documentation/web-api/concepts/spotify-uris-ids) for the category.

            '
          example: dinner
          type: string
      - name: locale
        required: false
        in: query
        schema:
          title: Locale
          description: 'The desired language, consisting of an [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) language code and an [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), joined by an underscore. For example: `es_MX`, meaning &quot;Spanish (Mexico)&quot;. Provide this parameter if you want the category strings returned in a particular language.<br/> _**Note**: if `locale` is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English)._

            '
          example: sv_SE
          type: string
      responses:
        '200':
          $ref: '#/components/responses/OneCategory'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /browse/categories/{category_id}/playlists:
    get:
      deprecated: true
      tags:
      - Categories
      operationId: get-a-categories-playlists
      summary: 'Get Category''s Playlists

        '
      description: 'Get a list of Spotify playlists tagged with a particular category.

        '
      parameters:
      - name: category_id
        required: true
        in: path
        schema:
          title: Category ID
          description: 'The [Spotify category ID](/documentation/web-api/concepts/spotify-uris-ids) for the category.

            '
          example: dinner
          type: string
      - $ref: '#/components/parameters/QueryLimit'
      - $ref: '#/components/parameters/QueryOffset'
      responses:
        '200':
          $ref: '#/components/responses/PagedFeaturedPlaylists'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
components:
  schemas:
    SimplifiedPlaylistObject:
      type: object
      x-spotify-docs-type: SimplifiedPlaylistObject
      properties:
        collaborative:
          type: boolean
          description: '`true` if the owner allows other users to modify the playlist.

            '
        description:
          type: string
          description: 'The playlist description. _Only returned for modified, verified playlists, otherwise_ `null`.

            '
        external_urls:
          allOf:
          - $ref: '#/components/schemas/ExternalUrlObject'
          description: 'Known external URLs for this playlist.

            '
        href:
          type: string
          description: 'A link to the Web API endpoint providing full details of the playlist.

            '
        id:
          type: string
          description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the playlist.

            '
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageObject'
          description: 'Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See [Working with Playlists](/documentation/web-api/concepts/playlists). _**Note**: If returned, the source URL for the image (`url`) is temporary and will expire in less than a day._

            '
        name:
          type: string
          description: 'The name of the playlist.

            '
        owner:
          allOf:
          - $ref: '#/components/schemas/PlaylistOwnerObject'
          description: 'The user who owns the playlist

            '
        public:
          type: boolean
          description: 'The playlist''s public/private status (if it is added to the user''s profile): `true` the playlist is public, `false` the playlist is private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](/documentation/web-api/concepts/playlists)

            '
        snapshot_id:
          type: string
          description: 'The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version

            '
        items:
          allOf:
          - $ref: '#/components/schemas/PlaylistTracksRefObject'
          description: 'A collection containing a link ( `href` ) to the Web API endpoint where full details of the playlist''s items can be retrieved, along with the `total` number of items in the playlist. Note, a track object may be `null`. This can happen if a track is no longer available.

            '
        tracks:
          allOf:
          - $ref: '#/components/schemas/PlaylistTracksRefObject'
          deprecated: true
          description: '**Deprecated:** Use `items` instead. A collection containing a link ( `href` ) to the Web API endpoint where full details of the playlist''s tracks can be retrieved, along with the `total` number of tracks in the playlist. Note, a track object may be `null`. This can happen if a track is no longer available.

            '
        type:
          type: string
          description: 'The object type: "playlist"

            '
        uri:
          type: string
          description: 'The [Spotify URI](/documentation/web-api/concepts/spotify-uris-ids) for the playlist.

            '
    ExternalUrlObject:
      type: object
      x-spotify-docs-type: ExternalUrlObject
      properties:
        spotify:
          type: string
          description: 'The [Spotify URL](/documentation/web-api/concepts/spotify-uris-ids) for the object.

            '
    PlaylistUserObject:
      type: object
      x-spotify-docs-type: PlaylistUserObject
      properties:
        external_urls:
          allOf:
          - $ref: '#/components/schemas/ExternalUrlObject'
          description: 'Known public external URLs for this user.

            '
        href:
          type: string
          description: 'A link to the Web API endpoint for this user.

            '
        id:
          type: string
          description: 'The [Spotify user ID](/documentation/web-api/concepts/spotify-uris-ids) for this user.

            '
        type:
          type: string
          enum:
          - user
          description: 'The object type.

            '
        uri:
          type: string
          description: 'The [Spotify URI](/documentation/web-api/concepts/spotify-uris-ids) for this user.

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

            '
    PagingPlaylistObject:
      type: object
      x-spotify-docs-type: PagingPlaylistObject
      allOf:
      - $ref: '#/components/schemas/PagingObject'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/SimplifiedPlaylistObject'
    ImageObject:
      type: object
      x-spotify-docs-type: ImageObject
      required:
      - url
      - height
      - width
      properties:
        url:
          type: string
          example: 'https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228

            '
          description: 'The source URL of the image.

            '
        height:
          type: integer
          example: 300
          nullable: true
          description: 'The image height in pixels.

            '
        width:
          type: integer
          example: 300
          nullable: true
          description: 'The image width in pixels.

            '
    PagingFeaturedPlaylistObject:
      type: object
      x-spotify-docs-type: PagingFeaturedPlaylistObject
      properties:
        message:
          type: string
          description: 'The localized message of a playlist.

            '
          example: Popular Playlists
        playlists:
          $ref: '#/components/schemas/PagingPlaylistObject'
    PagingObject:
      type: object
      x-spotify-docs-type: PagingObject
      required:
      - href
      - items
      - limit
      - next
      - offset
      - previous
      - total
      properties:
        href:
          type: string
          example: 'https://api.spotify.com/v1/me/shows?offset=0&limit=20

            '
          description: 'A link to the Web API endpoint returning the full result of the request

            '
        limit:
          type: integer
          example: 20
          description: 'The maximum number of items in the response (as set in the query or by default).

            '
        next:
          type: string
          example: https://api.spotify.com/v1/me/shows?offset=1&limit=1
          nullable: true
          description: 'URL to the next page of items. ( `null` if none)

            '
        offset:
          type: integer
          example: 0
          description: 'The offset of the items returned (as set in the query or by default)

            '
        previous:
          type: string
          example: https://api.spotify.com/v1/me/shows?offset=1&limit=1
          nullable: true
          description: 'URL to the previous page of items. ( `null` if none)

            '
        total:
          type: integer
          example: 4
          description: 'The total number of items available to return.

            '
    PlaylistTracksRefObject:
      type: object
      x-spotify-docs-type: PlaylistTracksRefObject
      properties:
        href:
          type: string
          description: 'A link to the Web API endpoint where full details of the playlist''s tracks can be retrieved.

            '
        total:
          type: integer
          description: 'Number of tracks in the playlist.

            '
    CategoryObject:
      type: object
      x-spotify-docs-type: CategoryObject
      required:
      - href
      - icons
      - id
      - name
      properties:
        href:
          type: string
          description: 'A link to the Web API endpoint returning full details of the category.

            '
        icons:
          type: array
          items:
            $ref: '#/components/schemas/ImageObject'
          description: 'The category icon, in various sizes.

            '
        id:
          type: string
          example: equal
          description: 'The [Spotify category ID](/documentation/web-api/concepts/spotify-uris-ids) of the category.

            '
        name:
          type: string
          example: EQUAL
          description: 'The name of the category.

            '
    PlaylistOwnerObject:
      allOf:
      - $ref: '#/components/schemas/PlaylistUserObject'
      - type: object
        properties:
          display_name:
            type: string
            nullable: true
            description: 'The name displayed on the user''s profile. `null` if not available.

              '
  responses:
    PagedFeaturedPlaylists:
      description: A paged set of playlists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PagingFeaturedPlaylistObject'
    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'
    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'
    PagedCategories:
      description: A paged set of categories
      content:
        application/json:
          schema:
            type: object
            required:
            - categories
            properties:
              categories:
                type: object
                allOf:
                - $ref: '#/components/schemas/PagingObject'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/CategoryObject'
    TooManyRequests:
      description: 'The app has exceeded its rate limits.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    OneCategory:
      description: A category
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CategoryObject'
  parameters:
    QueryOffset:
      name: offset
      required: false
      in: query
      schema:
        title: Offset
        description: 'The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

          '
        default: 0
        example: 5
        type: integer
    QueryLimit:
      name: limit
      required: false
      in: query
      schema:
        title: Limit
        description: 'The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

          '
        default: 20
        example: 10
        type: integer
        minimum: 0
        maximum: 50
  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.

              '