Spotify Chapters 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 Chapters 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: Chapters
paths:
  /chapters/{id}:
    get:
      operationId: get-a-chapter
      x-spotify-policy-list:
        $ref: '#/components/x-spotify-policy/metadataPolicyList'
      tags:
      - Chapters
      summary: Get a Chapter
      description: Get Spotify catalog information for a single audiobook chapter. Chapters are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
      parameters:
      - $ref: '#/components/parameters/PathChapterId'
      - $ref: '#/components/parameters/QueryMarket'
      responses:
        '200':
          $ref: '#/components/responses/OneChapter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /chapters:
    get:
      deprecated: true
      operationId: get-several-chapters
      x-spotify-policy-list:
        $ref: '#/components/x-spotify-policy/metadataPolicyList'
      tags:
      - Chapters
      summary: Get Several Chapters
      description: Get Spotify catalog information for several audiobook chapters identified by their Spotify IDs. Chapters are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
      parameters:
      - $ref: '#/components/parameters/QueryChapterIds'
      - $ref: '#/components/parameters/QueryMarket'
      responses:
        '200':
          $ref: '#/components/responses/ManyChapters'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
components:
  schemas:
    SimplifiedAudiobookObject:
      x-spotify-docs-type: SimplifiedAudiobookObject
      allOf:
      - $ref: '#/components/schemas/AudiobookBase'
      - type: object
    ChapterObject:
      x-spotify-docs-type: ChapterObject
      type: object
      allOf:
      - $ref: '#/components/schemas/ChapterBase'
      - type: object
        required:
        - audiobook
        properties:
          audiobook:
            allOf:
            - $ref: '#/components/schemas/SimplifiedAudiobookObject'
            description: 'The audiobook for which the chapter belongs.

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

            '
    ChapterBase:
      type: object
      required:
      - audio_preview_url
      - chapter_number
      - description
      - html_description
      - duration_ms
      - explicit
      - external_urls
      - href
      - id
      - images
      - is_playable
      - languages
      - name
      - release_date
      - release_date_precision
      - type
      - uri
      properties:
        audio_preview_url:
          deprecated: true
          type:
          - string
          - 'null'
          example: https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17
          description: 'A URL to a 30 second preview (MP3 format) of the chapter. `null` if not available.

            '
          x-spotify-policy-list:
          - $ref: '#/components/x-spotify-policy/policies/StandalonePreview'
        available_markets:
          deprecated: true
          type: array
          items:
            type: string
          description: 'A list of the countries in which the chapter can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.

            '
        chapter_number:
          type: integer
          example: 1
          description: 'The number of the chapter

            '
        description:
          type: string
          example: 'We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.

            '
          description: 'A description of the chapter. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed.

            '
        html_description:
          type: string
          example: '<p>We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.</p>

            '
          description: 'A description of the chapter. This field may contain HTML tags.

            '
        duration_ms:
          type: integer
          example: 1686230
          description: 'The chapter length in milliseconds.

            '
        explicit:
          type: boolean
          description: 'Whether or not the chapter has explicit content (true = yes it does; false = no it does not OR unknown).

            '
        external_urls:
          allOf:
          - $ref: '#/components/schemas/ExternalUrlObject'
          description: 'External URLs for this chapter.

            '
        href:
          type: string
          example: https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ
          description: 'A link to the Web API endpoint providing full details of the chapter.

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

            '
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageObject'
          description: 'The cover art for the chapter in various sizes, widest first.

            '
        is_playable:
          type: boolean
          description: 'True if the chapter is playable in the given market. Otherwise false.

            '
        languages:
          type: array
          items:
            type: string
          example:
          - fr
          - en
          description: 'A list of the languages used in the chapter, identified by their [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639) code.

            '
        name:
          type: string
          example: 'Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators

            '
          description: 'The name of the chapter.

            '
        release_date:
          type: string
          example: '1981-12-15'
          description: 'The date the chapter was first released, for example `"1981-12-15"`. Depending on the precision, it might be shown as `"1981"` or `"1981-12"`.

            '
        release_date_precision:
          type: string
          example: day
          enum:
          - year
          - month
          - day
          description: 'The precision with which `release_date` value is known.

            '
        resume_point:
          allOf:
          - $ref: '#/components/schemas/ResumePointObject'
          description: 'The user''s most recent position in the chapter. Set if the supplied access token is a user token and has the scope ''user-read-playback-position''.

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

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

            '
        restrictions:
          allOf:
          - $ref: '#/components/schemas/ChapterRestrictionObject'
          description: 'Included in the response when a content restriction is applied.

            '
    CopyrightObject:
      type: object
      x-spotify-docs-type: CopyrightObject
      properties:
        text:
          type: string
          description: 'The copyright text for this content.

            '
        type:
          type: string
          description: 'The type of copyright: `C` = the copyright, `P` = the sound recording (performance) copyright.

            '
    NarratorObject:
      type: object
      x-spotify-docs-type: NarratorObject
      properties:
        name:
          type: string
          description: 'The name of the Narrator.

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

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

            '
    ChapterRestrictionObject:
      type: object
      x-spotify-docs-type: ChapterRestrictionObject
      properties:
        reason:
          type: string
          description: 'The reason for the restriction. Supported values:

            - `market` - The content item is not available in the given market.

            - `product` - The content item is not available for the user''s subscription type.

            - `explicit` - The content item is explicit and the user''s account is set to not play explicit content.

            - `payment_required` - Payment is required to play the content item.


            Additional reasons may be added in the future.

            **Note**: If you use this field, make sure that your application safely handles unknown values.

            '
    AudiobookBase:
      type: object
      required:
      - authors
      - available_markets
      - copyrights
      - description
      - explicit
      - external_urls
      - href
      - html_description
      - id
      - images
      - languages
      - media_type
      - name
      - narrators
      - publisher
      - total_chapters
      - type
      - uri
      properties:
        authors:
          type: array
          items:
            $ref: '#/components/schemas/AuthorObject'
          description: 'The author(s) for the audiobook.

            '
        available_markets:
          deprecated: true
          type: array
          items:
            type: string
          description: 'A list of the countries in which the audiobook can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.

            '
        copyrights:
          type: array
          items:
            $ref: '#/components/schemas/CopyrightObject'
          description: 'The copyright statements of the audiobook.

            '
        description:
          type: string
          description: 'A description of the audiobook. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed.

            '
        html_description:
          type: string
          description: 'A description of the audiobook. This field may contain HTML tags.

            '
        edition:
          type: string
          description: 'The edition of the audiobook.

            '
          example: Unabridged
        explicit:
          type: boolean
          description: 'Whether or not the audiobook has explicit content (true = yes it does; false = no it does not OR unknown).

            '
        external_urls:
          allOf:
          - $ref: '#/components/schemas/ExternalUrlObject'
          description: 'External URLs for this audiobook.

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

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

            '
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageObject'
          description: 'The cover art for the audiobook in various sizes, widest first.

            '
        languages:
          type: array
          items:
            type: string
          description: 'A list of the languages used in the audiobook, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code.

            '
        media_type:
          type: string
          description: 'The media type of the audiobook.

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

            '
        narrators:
          type: array
          items:
            $ref: '#/components/schemas/NarratorObject'
          description: 'The narrator(s) for the audiobook.

            '
        publisher:
          deprecated: true
          type: string
          description: 'The publisher of the audiobook.

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

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

            '
        total_chapters:
          type: integer
          description: 'The number of chapters in this audiobook.

            '
    AuthorObject:
      type: object
      x-spotify-docs-type: AuthorObject
      properties:
        name:
          type: string
          description: 'The name of the author.

            '
    ResumePointObject:
      type: object
      x-spotify-docs-type: ResumePointObject
      properties:
        fully_played:
          type: boolean
          description: 'Whether or not the episode has been fully played by the user.

            '
        resume_position_ms:
          type: integer
          description: 'The user''s most recent position in the episode in milliseconds.

            '
  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'
    ManyChapters:
      description: A set of chapters
      content:
        application/json:
          schema:
            type: object
            required:
            - chapters
            properties:
              chapters:
                type: array
                items:
                  $ref: '#/components/schemas/ChapterObject'
    OneChapter:
      description: A Chapter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ChapterObject'
    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'
  x-spotify-policy:
    metadataPolicyList:
    - $ref: '#/components/x-spotify-policy/policies/Downloading'
    - $ref: '#/components/x-spotify-policy/policies/VisualAlteration'
    - $ref: '#/components/x-spotify-policy/policies/Attribution'
  parameters:
    QueryChapterIds:
      name: ids
      required: true
      in: query
      schema:
        title: Spotify Chapter IDs
        description: 'A comma-separated list of the [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids). For example: `ids=0IsXVP0JmcB2adSE338GkK,3ZXb8FKZGU0EHALYX6uCzU`. Maximum: 50 IDs.

          '
        example: 0IsXVP0JmcB2adSE338GkK,3ZXb8FKZGU0EHALYX6uCzU,0D5wENdkdwbqlrHoaJ9g29
        type: string
    QueryMarket:
      name: market
      required: false
      in: query
      schema:
        title: Market
        description: "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n  If a country code is specified, only content that is available in that market will be returned.<br/>\n  If a valid user access token is specified in the request header, the country associated with\n  the user account will take priority over this parameter.<br/>\n  _**Note**: If neither market or user country are provided, the content is considered unavailable for the client._<br/>\n  Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/).\n"
        example: ES
        type: string
    PathChapterId:
      name: id
      required: true
      in: path
      schema:
        title: Spotify Chapter ID
        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids)

          for the chapter.

          '
        example: 0D5wENdkdwbqlrHoaJ9g29
        type: string
  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.

              '