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 OAuth 2.0. The base URI for all Web API requests is `https://api.spotify.com/v1`. Need help? See our Web API guides for more information, or visit the Spotify for Developers community forum to ask questions and connect with other developers. ' version: 1.0.0 title: Spotify Web Albums 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](/documentation/web-api/reference/save-library-items) 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](/documentation/web-api/reference/remove-library-items) 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](/documentation/web-api/reference/check-library-contains) 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: 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' schemas: 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 nullable: true 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: '

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. 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. ' NarratorObject: type: object x-spotify-docs-type: NarratorObject properties: name: type: string description: 'The name of the Narrator. ' SimplifiedChapterObject: x-spotify-docs-type: SimplifiedChapterObject type: object allOf: - $ref: '#/components/schemas/ChapterBase' - type: object 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. ' AuthorObject: type: object x-spotify-docs-type: AuthorObject properties: name: type: string description: 'The name of the author. ' 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. ' PagingSimplifiedChapterObject: type: object x-spotify-docs-type: PagingSimplifiedChapterObject allOf: - $ref: '#/components/schemas/PagingObject' - type: object properties: items: type: array items: $ref: '#/components/schemas/SimplifiedChapterObject' 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. ' SimplifiedAudiobookObject: x-spotify-docs-type: SimplifiedAudiobookObject allOf: - $ref: '#/components/schemas/AudiobookBase' - type: object 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. ' 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. ' 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. ' 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. ' 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: 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' 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' 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' NotFound: description: 'The requested resource cannot be found. ' content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' PagingSimplifiedChapterObject: description: Pages of chapters content: application/json: schema: $ref: '#/components/schemas/PagingSimplifiedChapterObject' 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 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' TooManyRequests: description: 'The app has exceeded its rate limits. ' content: application/json: schema: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' 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 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.
\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.
\n _**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
\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 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 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. '