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 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:
/audiobooks/{id}/chapters:
get:
operationId: get-audiobook-chapters
x-spotify-policy-list:
$ref: '#/components/x-spotify-policy/metadataPolicyList'
tags:
- Chapters
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: []
/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:
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'
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.
'
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.
'
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
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
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'
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'
PagingSimplifiedChapterObject:
description: Pages of chapters
content:
application/json:
schema:
$ref: '#/components/schemas/PagingSimplifiedChapterObject'
ManyChapters:
description: A set of chapters
content:
application/json:
schema:
type: object
required:
- chapters
properties:
chapters:
type: array
items:
$ref: '#/components/schemas/ChapterObject'
TooManyRequests:
description: 'The app has exceeded its rate limits.
'
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
OneChapter:
description: A Chapter
content:
application/json:
schema:
$ref: '#/components/schemas/ChapterObject'
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.
'