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