Spotify Categories 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 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: []
components:
  responses:
    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'
    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'
    OneCategory:
      description: A category
      content:
        application/json:
          schema:
            $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'
  schemas:
    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
          - 'null'
          example: 300
          description: 'The image height in pixels.

            '
        width:
          type:
          - integer
          - 'null'
          example: 300
          description: 'The image width in pixels.

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

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

            '
    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
          - 'null'
          example: https://api.spotify.com/v1/me/shows?offset=1&limit=1
          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
          - 'null'
          example: https://api.spotify.com/v1/me/shows?offset=1&limit=1
          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.

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

              '