Playlists Endpoint Reference

Functions

async add_custom_playlist_cover_image(client: SpotanticClient, *, playlist_id: SpotifyItemID, image_data: bytes | None = None, file_path: Annotated[Path, PathType(path_type=file)] | None = None) → APICallModel[AddCustomPlaylistCoverImageRequest, RawAPIResponse, NoneType]

Replace the image used to represent a specific playlist.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
image_data – The image data as bytes. Must be a JPEG image, maximum size 256 KB.
file_path – The file path to a JPEG image. Must be maximum size 256 KB.

Returns:

An object containing the request used to obtain the response and the response.

async add_items_to_playlist(client: SpotanticClient, *, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI], position: int | None = None) → APICallModel[AddItemsToPlaylistRequest, JsonAPIResponse, PlaylistSnapshotResponseModel]

Add one or more items to a user’s playlist.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to add.
position – The position to insert the items, or None to add to the end.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async change_playlist_details(client: SpotanticClient, *, playlist_id: SpotifyItemID, name: str | None = None, public: bool | None = None, collaborative: bool | None = None, description: str | None = None) → APICallModel[ChangePlaylistDetailsRequest, RawAPIResponse, NoneType]

Change a playlist’s name and public/private state.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
name – The new name for the playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.
description – The new description for the playlist.

Returns:

An object containing the request used to obtain the response and the response.

async create_playlist(client: SpotanticClient, *, name: str, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → APICallModel[CreatePlaylistRequest, JsonAPIResponse, PlaylistModel]

Create a playlist for the current Spotify user.

Each user is generally limited to a maximum of 11000 playlists.

Parameters:

client – SpotanticClient instance.
name – The name for the new playlist.
description – The description for the new playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async create_playlist_for_user(client: SpotanticClient, *, user_id: str, name: str, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → APICallModel[CreatePlaylistForUserRequest, JsonAPIResponse, PlaylistModel]

Create a playlist for a Spotify user.

Each user is generally limited to a maximum of 11000 playlists.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security. Use Create Playlist instead.

Parameters:

client – SpotanticClient instance.
user_id – The Spotify user ID of the user.
name – The name for the new playlist.
description – The description for the new playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_current_user_playlist(client: SpotanticClient, *, limit: int = 20, offset: int = 0) → APICallModel[GetCurrentUserPlaylistsRequest, JsonAPIResponse, PagedResultModel[SimplifiedPlaylistModel]]

Get a list of the playlists owned or followed by the current Spotify user.

Parameters:

client – SpotanticClient instance.
limit – The maximum number of playlists to return. Default is 20. Minimum is 1, maximum is 50.
offset – The index of the first playlist to return. Default is 0.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_playlist(client: SpotanticClient, *, playlist_id: SpotifyItemID, fields: str | None = None, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → APICallModel[GetPlaylistRequest, JsonAPIResponse, PlaylistModel]

Get a playlist owned by a Spotify user.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
fields – Filters for the query: a comma-separated list of the fields to return.
additional_types – A list of item types to include in the response.
market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_playlist_cover_image(client: SpotanticClient, *, playlist_id: SpotifyItemID) → APICallModel[GetPlaylistCoverImageRequest, JsonAPIResponse, list[ImageModel]]

Get the current image associated with a specific playlist.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_playlist_items(client: SpotanticClient, *, playlist_id: SpotifyItemID, fields: str | None = None, limit: int = 20, offset: int = 0, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → APICallModel[GetPlaylistItemsRequest, JsonAPIResponse, PagedResultModel[PlaylistTrackModel]]

Get full details of the items of a playlist owned by a Spotify user.

Note: This endpoint is only accessible for playlists owned by the current user or playlists the user is a collaborator of. A 403 Forbidden status code will be returned if the user is neither the owner nor a collaborator of the playlist.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
fields – Filters for the query: a comma-separated list of the fields to return.
limit – The maximum number of items to return. Default is 20. Minimum is 1, maximum is 50.
offset – The index of the first item to return. Default is 0.
additional_types – A list of item types to include in the response.
market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_user_playlists(client: SpotanticClient, *, user_id: str, limit: int = 20, offset: int = 0) → APICallModel[GetUserPlaylistsRequest, JsonAPIResponse, PagedResultModel[SimplifiedPlaylistModel]]

Get a list of the playlists owned or followed by a Spotify user.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security.

Parameters:

client – SpotanticClient instance.
user_id – The Spotify user ID of the user.
limit – The maximum number of playlists to return. Default is 20. Minimum is 1, maximum is 50.
offset – The index of the first playlist to return. Default is 0.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async remove_playlist_items(client: SpotanticClient, *, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI], snapshot_id: str | None = None) → APICallModel[RemovePlaylistItemsRequest, JsonAPIResponse, PlaylistSnapshotResponseModel]

Remove one or more items from a user’s playlist.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to remove.
snapshot_id – The playlist’s snapshot ID.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async update_playlist_items(client: SpotanticClient, *, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None = None, range_start: int, insert_before: int, range_length: int = 1, snapshot_id: str | None = None) → APICallModel[UpdatePlaylistItemsRequest, JsonAPIResponse, PlaylistSnapshotResponseModel]

Reorder items in a playlist.

Either reorder or replace items in a playlist depending on the request’s parameters. To reorder items, include range_start, insert_before, range_length and snapshot_id in the request’s body. To replace items, include uris as either a query parameter or in the request’s body. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist. These operations can’t be applied together in a single request.

Parameters:

client – SpotanticClient instance.
playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to update.
range_start – The position of the first item to be reordered.
insert_before – The position where the items should be inserted.
range_length – The number of items to be reordered. Default is 1.
snapshot_id – The playlist’s snapshot ID.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

Request models

class AddCustomPlaylistCoverImageRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC, AuthScope.UGC_IMAGE_UPLOAD}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='image/jpeg', content_length=None, content_encoding=None, content_language=None), params: AddCustomPlaylistCoverImageRequestParams | None = None, body: AddCustomPlaylistCoverImageRequestBody | None = None)

Bases: RequestModel[AddCustomPlaylistCoverImageRequestParams, AddCustomPlaylistCoverImageRequestBody]

Request model for Add Custom Playlist Cover Image endpoint.

classmethod build(*, playlist_id: SpotifyItemID, image_data: bytes | None = None, file_path: Annotated[Path, PathType(path_type=file)] | None = None) → AddCustomPlaylistCoverImageRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
image_data – The image data as bytes. Must be a JPEG image, maximum size 256 KB.
file_path – The file path to a JPEG image. Must be maximum size 256 KB.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class AddCustomPlaylistCoverImageRequestBody(*, image_data: bytes | None = None, file_path: Annotated[Path, PathType(path_type=file)] | None = None)

Bases: RequestBodyModel

Body model for Add Custom Playlist Cover Image request.

get_image_data_from_file() → AddCustomPlaylistCoverImageRequestBody

Loads image data from file if file_path is provided and image_data is None.

Returns:: The validated model with image_data populated.
Raises:: ValueError – If neither image_data nor file_path is provided. Or if the file is not a JPEG image.

to_http_body() → str | bytes | None

Converts the model to the appropriate HTTP body format.

For this request, the body should be the raw image data as bytes.

Returns:: The image data as bytes, or None if no image data is available.

file_path: FilePath | None: The file path to a JPEG image.

image_data: bytes | None: The image data as bytes.

class AddCustomPlaylistCoverImageRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Add Custom Playlist Cover Image request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class AddItemsToPlaylistRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: AddItemsToPlaylistRequestParams | None = None, body: AddItemsToPlaylistRequestBody | None = None)

Bases: RequestModel[AddItemsToPlaylistRequestParams, AddItemsToPlaylistRequestBody]

Request model for Add Items to Playlist endpoint.

classmethod build(*, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI], position: int | None = None) → AddItemsToPlaylistRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to add.
position – The position to insert the items, or None to add to the end.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class AddItemsToPlaylistRequestBody(*, uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI], MaxLen(max_length=100)], position: int | None = None)

Bases: RequestBodyJsonModel

Body model for Add Items to Playlist request.

position: int | None: The position to insert the items.

uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI], Field(max_length=100)]: A list of Spotify URIs for the items to add.

class AddItemsToPlaylistRequestParams(*, playlist_id: SpotifyItemID, position: int | None = None, uris: sequence_to_comma_separated_str, return_type=str, when_used=unless - none)] = None)

Bases: BaseModel

Params model for Add Items to Playlist request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

position: int | None: The position to insert the items.

uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None, Field(max_length=100), PlainSerializer(sequence_to_comma_separated_str, return_type=str, when_used='unless-none')]: A list of Spotify URIs for the items to add.

class ChangePlaylistDetailsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: ChangePlaylistDetailsRequestParams | None = None, body: ChangePlaylistDetailsRequestBody | None = None)

Bases: RequestModel[ChangePlaylistDetailsRequestParams, ChangePlaylistDetailsRequestBody]

Request model for Change Playlist Details endpoint.

classmethod build(*, playlist_id: SpotifyItemID, name: str | None = None, public: bool | None = None, collaborative: bool | None = None, description: str | None = None) → ChangePlaylistDetailsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
name – The new name for the playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.
description – The new description for the playlist.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class ChangePlaylistDetailsRequestBody(*, name: str | None = None, public: bool | None = None, collaborative: bool | None = None, description: str | None = None)

Bases: RequestBodyJsonModel

Body model for Change Playlist Details request.

collaborative: bool | None: Whether the playlist should be collaborative.

description: str | None: The new description for the playlist.

name: str | None: The new name for the playlist.

public: bool | None: Whether the playlist should be public.

class ChangePlaylistDetailsRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Change Playlist Details request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class CreatePlaylistForUserRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: CreatePlaylistForUserRequestParams | None = None, body: CreatePlaylistForUserRequestBody | None = None)

Bases: RequestModel[CreatePlaylistForUserRequestParams, CreatePlaylistForUserRequestBody]

Request model for Create Playlist For User endpoint.

classmethod build(*, user_id: str, name: str, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → CreatePlaylistForUserRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

user_id – The Spotify user ID of the playlist owner.
name – The name for the new playlist.
description – The description for the new playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class CreatePlaylistForUserRequestBody(*, name: str, public: bool | None = None, collaborative: bool | None = None, description: str | None = None)

Bases: RequestBodyJsonModel

Body model for Create Playlist For User request.

validate_flags() → CreatePlaylistForUserRequestBody

Validates the public and collaborative flags.

Returns:: The validated model.
Raises:: ValueError – If public is False and collaborative is True.

collaborative: bool | None: Whether the playlist should be collaborative.

description: str | None: The description for the new playlist.

name: str: The name for the new playlist.

public: bool | None: Whether the playlist should be public.

class CreatePlaylistForUserRequestParams(*, user_id: str)

Bases: BaseModel

Params model for Create Playlist For User request.

user_id: str: The Spotify user ID of the playlist owner.

class CreatePlaylistRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = 'me/playlists', method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: None = None, body: CreatePlaylistRequestBody | None = None)

Bases: RequestModel[NoneType, CreatePlaylistRequestBody]

Request model for Create Playlist endpoint.

classmethod build(*, name: str, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → CreatePlaylistRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

user_id – The Spotify user ID of the playlist owner.
name – The name for the new playlist.
description – The description for the new playlist.
public – Whether the playlist should be public.
collaborative – Whether the playlist should be collaborative.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class CreatePlaylistRequestBody(*, name: str, public: bool | None = None, collaborative: bool | None = None, description: str | None = None)

Bases: RequestBodyJsonModel

Body model for Create Playlist request.

validate_flags() → CreatePlaylistRequestBody

Validates the public and collaborative flags.

Returns:: The validated model.
Raises:: ValueError – If public is False and collaborative is True.

collaborative: bool | None: Whether the playlist should be collaborative.

description: str | None: The description for the new playlist.

name: str: The name for the new playlist.

public: bool | None: Whether the playlist should be public.

class GetCurrentUserPlaylistsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_READ_PRIVATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/playlists', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetCurrentUserPlaylistsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetCurrentUserPlaylistsRequestParams, NoneType]

Request model for Get Current User’s Playlists endpoint.

classmethod build(*, limit: int = 20, offset: int = 0) → GetCurrentUserPlaylistsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

limit – The maximum number of playlists to return.
offset – The index of the first playlist to return.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetCurrentUserPlaylistsRequestParams(*, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: Annotated[int, Ge(ge=0), Le(le=100000)])

Bases: BaseModel

Params model for Get Current User’s Playlists request.

limit: Annotated[int, Field(ge=1, le=50)]: The maximum number of playlists to return.

offset: Annotated[int, Field(ge=0, le=100000)]: The index of the first playlist to return.

class GetPlaylistCoverImageRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetPlaylistCoverImageRequestParams | None = None, body: None = None)

Bases: RequestModel[GetPlaylistCoverImageRequestParams, NoneType]

Request model for Get Playlist Cover Image endpoint.

classmethod build(*, playlist_id: SpotifyItemID) → GetPlaylistCoverImageRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:: playlist_id – The Spotify ID of the playlist.
Returns:: Validated Request object.

method_type: HTTPMethod: HTTP method for the request.

class GetPlaylistCoverImageRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Get Playlist Cover Image request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class GetPlaylistItemsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_READ_PRIVATE}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetPlaylistItemsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetPlaylistItemsRequestParams, NoneType]

Request model for Get Playlist Items endpoint.

classmethod build(*, playlist_id: SpotifyItemID, fields: str | None = None, limit: int = 20, offset: int = 0, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → GetPlaylistItemsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
fields – Filters for the response data.
limit – The maximum number of items to return.
offset – The index of the first item to return.
additional_types – A list of item types to return.
market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetPlaylistItemsRequestParams(*, playlist_id: SpotifyItemID, fields: str | None = None, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int, additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Playlist Items request.

classmethod check_value_is_playback_supported(value: Sequence[SpotifyItemType]) → Sequence[SpotifyItemType]

Validates that the additional types are supported by playback.

Parameters:: value – The sequence of SpotifyItemType to validate.
Returns:: The validated sequence of SpotifyItemType.
Raises:: ValueError – If any item in the sequence is not supported by playback.

additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(sequence_to_comma_separated_str, return_type=str)]: A list of item types to return.

fields: str | None: Filters for the response data.

limit: Annotated[int, Field(ge=1, le=50)]: The maximum number of items to return.

market: SpotifyMarketID | None: An ISO 3166-1 alpha-2 country code.

offset: int: The index of the first item to return.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class GetPlaylistRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetPlaylistRequestParams | None = None, body: None = None)

Bases: RequestModel[GetPlaylistRequestParams, NoneType]

Request model for Get Playlist endpoint.

classmethod build(*, playlist_id: SpotifyItemID, fields: str | None = None, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → GetPlaylistRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
fields – Filters for the response data.
additional_types – A list of item types to return.
market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

method_type: HTTPMethod: HTTP method for the request.

class GetPlaylistRequestParams(*, playlist_id: SpotifyItemID, fields: str | None = None, additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Playlist request.

classmethod check_value_is_playback_supported(value: Sequence[SpotifyItemType]) → Sequence[SpotifyItemType]

Validates that the additional types are supported by playback.

Parameters:: value – The sequence of SpotifyItemType to validate.
Returns:: The validated sequence of SpotifyItemType.
Raises:: ValueError – If any item in the sequence is not supported by playback.

additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(sequence_to_comma_separated_str, return_type=str)]: A list of item types to return.

fields: str | None: Filters for the response data.

market: SpotifyMarketID | None: An ISO 3166-1 alpha-2 country code.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class GetUserPlaylistsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_READ_PRIVATE}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetUserPlaylistsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetUserPlaylistsRequestParams, NoneType]

Request model for Get User’s Playlists endpoint.

classmethod build(*, user_id: str, limit: int = 20, offset: int = 0) → GetUserPlaylistsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

user_id – The Spotify user ID of the playlist owner.
limit – The maximum number of playlists to return.
offset – The index of the first playlist to return.

Returns:

Validated Request object.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetUserPlaylistsRequestParams(*, user_id: str, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: Annotated[int, Ge(ge=0), Le(le=100000)])

Bases: BaseModel

Params model for Get User’s Playlists request.

limit: Annotated[int, Field(ge=1, le=50)]: The maximum number of playlists to return.

offset: Annotated[int, Field(ge=0, le=100000)]: The index of the first playlist to return.

user_id: str: The Spotify user ID of the playlist owner.

class RemovePlaylistItemsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.DELETE>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: RemovePlaylistItemsRequestParams | None = None, body: RemovePlaylistItemsRequestBody | None = None)

Bases: RequestModel[RemovePlaylistItemsRequestParams, RemovePlaylistItemsRequestBody]

Request model for Remove Playlist Items endpoint.

classmethod build(*, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI], snapshot_id: str | None = None) → RemovePlaylistItemsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to remove.
snapshot_id – The playlist’s snapshot ID.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class RemovePlaylistItemsRequestBody(*, items: ~typing.Annotated[~collections.abc.Sequence[~spotantic.types.SpotifyEpisodeURI | ~spotantic.types.SpotifyTrackURI], ~annotated_types.MaxLen(max_length=100), ~pydantic.functional_serializers.PlainSerializer(func=~spotantic.models.playlists.requests._remove_playlist_items.<lambda>, return_type=list[dict[str, str]], when_used=always)], snapshot_id: str | None = None)

Bases: RequestBodyJsonModel

Body model for Remove Playlist Items request.

items: Annotated[Sequence[Union[SpotifyEpisodeURI, SpotifyTrackURI]], Field(max_length=100), PlainSerializer(lambda seq: [{'uri': uri} for uri in seq], return_type=list[dict[str, str]])]: A list of Spotify URIs for the items to remove.

snapshot_id: str | None: The playlist’s snapshot ID.

class RemovePlaylistItemsRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Remove Playlist Items request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

class UpdatePlaylistItemsRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: UpdatePlaylistItemsRequestParams | None = None, body: UpdatePlaylistItemsRequestBody | None = None)

Bases: RequestModel[UpdatePlaylistItemsRequestParams, UpdatePlaylistItemsRequestBody]

Request model for Update Playlist Items endpoint.

classmethod build(*, playlist_id: SpotifyItemID, uris: Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None = None, range_start: int, insert_before: int, range_length: int = 1, snapshot_id: str | None = None) → UpdatePlaylistItemsRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

playlist_id – The Spotify ID of the playlist.
uris – A list of Spotify URIs for the items to update.
range_start – The position of the first item to be moved.
insert_before – The position where the items should be inserted.
range_length – The number of items to be moved.
snapshot_id – The playlist’s snapshot ID.

Returns:

Validated Request object.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class UpdatePlaylistItemsRequestBody(*, uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None, MaxLen(max_length=100)] = None, range_start: int, insert_before: int, range_length: int | None = None, snapshot_id: str | None = None)

Bases: RequestBodyJsonModel

Body model for Update Playlist Items request.

insert_before: int: The position where the items should be inserted.

range_length: int | None: The number of items to be moved.

range_start: int: The position of the first item to be moved.

snapshot_id: str | None: The playlist’s snapshot ID.

uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None, Field(None, max_length=100)]: A list of Spotify URIs for the items to update.

class UpdatePlaylistItemsRequestParams(*, playlist_id: SpotifyItemID, uris: sequence_to_comma_separated_str, return_type=str, when_used=unless - none)] = None)

Bases: BaseModel

Params model for Update Playlist Items request.

playlist_id: SpotifyItemID: The Spotify ID of the playlist.

uris: Annotated[Sequence[SpotifyEpisodeURI | SpotifyTrackURI] | None, Field(None, max_length=100), PlainSerializer(sequence_to_comma_separated_str, return_type=str, when_used='unless-none')]: A list of Spotify URIs for the items to update.

Response models

class PlaylistSnapshotResponseModel(*, snapshot_id: str)

Bases: BaseModel

Response model for playlist snapshot ID.

snapshot_id: str: The snapshot ID of the playlist.