Spotify Audiobooks 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 Audiobooks 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: Audiobooks
paths:
  /audiobooks/{id}:
    get:
      operationId: get-an-audiobook
      x-spotify-policy-list:
        $ref: '#/components/x-spotify-policy/metadataPolicyList'
      tags:
      - Audiobooks
      summary: Get an Audiobook
      description: Get Spotify catalog information for a single audiobook. Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
      parameters:
      - $ref: '#/components/parameters/PathAudiobookId'
      - $ref: '#/components/parameters/QueryMarket'
      responses:
        '200':
          $ref: '#/components/responses/OneAudiobook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /audiobooks:
    get:
      deprecated: true
      operationId: get-multiple-audiobooks
      x-spotify-policy-list:
        $ref: '#/components/x-spotify-policy/metadataPolicyList'
      tags:
      - Audiobooks
      summary: Get Several Audiobooks
      description: Get Spotify catalog information for several audiobooks identified by their Spotify IDs. Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
      parameters:
      - $ref: '#/components/parameters/QueryAudiobookIds'
      - $ref: '#/components/parameters/QueryMarket'
      responses:
        '200':
          $ref: '#/components/responses/ManyAudiobooks'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /audiobooks/{id}/chapters:
    get:
      operationId: get-audiobook-chapters
      x-spotify-policy-list:
        $ref: '#/components/x-spotify-policy/metadataPolicyList'
      tags:
      - Audiobooks
      summary: Get Audiobook Chapters
      description: Get Spotify catalog information about an audiobook's chapters. Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
      parameters:
      - $ref: '#/components/parameters/PathAudiobookId'
      - $ref: '#/components/parameters/QueryMarket'
      - $ref: '#/components/parameters/QueryLimit'
      - $ref: '#/components/parameters/QueryOffset'
      responses:
        '200':
          $ref: '#/components/responses/PagingSimplifiedChapterObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0: []
  /me/audiobooks:
    get:
      tags:
      - Audiobooks
      operationId: get-users-saved-audiobooks
      summary: Get User's Saved Audiobooks
      description: Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library.
      parameters:
      - $ref: '#/components/parameters/QueryLimit'
      - $ref: '#/components/parameters/QueryOffset'
      responses:
        '200':
          $ref: '#/components/responses/PagingSimplifiedAudiobookObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-read
    put:
      deprecated: true
      tags:
      - Audiobooks
      operationId: save-audiobooks-user
      summary: Save Audiobooks for Current User
      description: 'Save one or more audiobooks to the current Spotify user''s library.


        **Note:** This endpoint is deprecated. Use Save Items to Library instead.'
      parameters:
      - $ref: '#/components/parameters/QueryAudiobookIds'
      responses:
        '200':
          description: Audiobook(s) are saved to the library
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-modify
    delete:
      deprecated: true
      tags:
      - Audiobooks
      operationId: remove-audiobooks-user
      summary: Remove User's Saved Audiobooks
      description: 'Remove one or more audiobooks from the Spotify user''s library.


        **Note:** This endpoint is deprecated. Use Remove Items from Library instead.'
      parameters:
      - $ref: '#/components/parameters/QueryAudiobookIds'
      responses:
        '200':
          description: Audiobook(s) have been removed from the library
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-modify
  /me/audiobooks/contains:
    get:
      tags:
      - Audiobooks
      operationId: check-users-saved-audiobooks
      summary: Check User's Saved Audiobooks
      deprecated: true
      description: 'Check if one or more audiobooks are already saved in the current Spotify user''s library.


        **Note:** This endpoint is deprecated. Use Check User''s Saved Items instead.'
      parameters:
      - $ref: '#/components/parameters/QueryAudiobookIds'
      responses:
        '200':
          $ref: '#/components/responses/ArrayOfBooleans'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth_2_0:
        - user-library-read
components:
  schemas:
    SimplifiedAudiobookObject:
      x-spotify-docs-type: SimplifiedAudiobookObject
      allOf:
      - $ref: '#/components/schemas/AudiobookBase'
      - type: object
    AudiobookObject:
      x-spotify-docs-type: AudiobookObject
      allOf:
      - $ref: '#/components/schemas/AudiobookBase'
      - type: object
        required:
        - chapters
        properties:
          chapters:
            type: object
            allOf:
            - $ref: '#/components/schemas/PagingSimplifiedChapterObject'
            description: 'The chapters of the audiobook.

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

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

            '
    PagingSimplifiedChapterObject:
      type: object
      x-spotify-docs-type: PagingSimplifiedChapterObject
      allOf:
      - $ref: '#/components/schemas/PagingObject'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/SimplifiedChapterObject'
    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.

            '
    SimplifiedChapterObject:
      x-spotify-docs-type: SimplifiedChapterObject
      type: object
      allOf:
      - $ref: '#/components/schemas/ChapterBase'
      - type: 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.

            '
    PagingSimplifiedAudiobookObject:
      type: object
      x-spotify-docs-type: PagingAudiobookObject
      allOf:
      - $ref: '#/components/schemas/PagingObject'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/SimplifiedAudiobookObject'
  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'
    ManyAudiobooks:
      description: A set of audiobooks. If one of the requested audiobooks is unavailable then you'll find a `null` item in the `audiobooks` array where the audiobook object would otherwise be.
      content:
        application/json:
          schema:
            type: object
            required:
            - audiobooks
            properties:
              audiobooks:
                type: array
                items:
                  $ref: '#/components/schemas/AudiobookObject'
    TooManyRequests:
      description: 'The app has exceeded its rate limits.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    NotFound:
      description: 'The requested resource cannot be found.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                $ref: '#/components/schemas/ErrorObject'
    PagingSimplifiedAudiobookObject:
      description: Pages of audiobooks
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PagingSimplifiedAudiobookObject'
    ArrayOfBooleans:
      description: Array of booleans
      content:
        application/json:
          schema:
            type: array
            example:
            - false
            - true
            items:
              type: boolean
    PagingSimplifiedChapterObject:
      description: Pages of chapters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PagingSimplifiedChapterObject'
    BadRequest:
      description: 'The request contains malformed data in path, query parameters, or body.

        '
      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'
    OneAudiobook:
      description: An Audiobook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AudiobookObject'
  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:
    QueryAudiobookIds:
      name: ids
      required: true
      in: query
      schema:
        title: Spotify Audiobook IDs
        description: 'A comma-separated list of the [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids). For example: `ids=18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ`. Maximum: 50 IDs.

          '
        example: 18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ,7iHfbu1YPACw6oZPAFJtqe
        type: string
    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
    PathAudiobookId:
      name: id
      required: true
      in: path
      schema:
        title: Spotify Audiobook ID
        description: 'The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids)

          for the audiobook.

          '
        example: 7iHfbu1YPACw6oZPAFJtqe
        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
    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.

              '