Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/innertube-v1/llms.txt

Use this file to discover all available pages before exploring further.

The playlist management API lets you create, rename, and delete playlists; add or remove individual songs or entire playlists; reorder tracks; and manage custom thumbnail images. All methods require an authenticated session (YouTube.cookie set). Most methods are suspend functions returning Result<T>.

​
YouTube.createPlaylist

Creates a new empty playlist with the given title and returns the new playlist’s ID. 
fun createPlaylist(title: String): String
Note: createPlaylist is implemented with runBlocking and is therefore a blocking call. Call it from a background thread or wrap it yourself in a coroutine if needed.
​
title
String
required
The display title for the new playlist.
Return type
​
String
String
The new playlist ID (e.g. "PLxxxxxxx").
Example 
val playlistId = YouTube.createPlaylist("My Workout Mix")
println("Created: $playlistId")

​
YouTube.renamePlaylist

Renames an existing playlist. 
suspend fun renamePlaylist(playlistId: String, name: String): Result<*>
​
playlistId
String
required
The ID of the playlist to rename.
​
name
String
required
The new display name for the playlist.
Return type
​
Result<*>
Result
Wraps the raw EditPlaylistResponse. Check Result.isSuccess to confirm the rename was accepted.
Example 
YouTube.renamePlaylist("PLxxxxxxx", "Evening Chill").onSuccess {
    println("Playlist renamed successfully.")
}

​
YouTube.deletePlaylist

Permanently deletes a playlist owned by the authenticated user. 
suspend fun deletePlaylist(playlistId: String): Result<*>
​
playlistId
String
required
The ID of the playlist to delete.
Return type
​
Result<*>
Result
Result.isSuccess is true when the API accepted the request.
Example 
YouTube.deletePlaylist("PLxxxxxxx").onSuccess {
    println("Playlist deleted.")
}.onFailure { e ->
    println("Error: ${e.message}")
}

​
YouTube.addToPlaylist

Adds a single video to the end of a playlist. 
suspend fun addToPlaylist(playlistId: String, videoId: String): Result<*>
​
playlistId
String
required
The target playlist’s ID.
​
videoId
String
required
The video ID to add.
Return type
​
Result<*>
Result
Wraps the raw HTTP response on success. Check Result.isSuccess to confirm the operation was accepted.
Example 
YouTube.addToPlaylist("PLxxxxxxx", "dQw4w9WgXcQ").onSuccess {
    println("Song added to playlist.")
}

​
YouTube.addPlaylistToPlaylist

Appends all tracks from one playlist into another playlist. 
suspend fun addPlaylistToPlaylist(playlistId: String, addPlaylistId: String): Result<*>
​
playlistId
String
required
The destination playlist’s ID.
​
addPlaylistId
String
required
The source playlist whose tracks will be appended.
Return type
​
Result<*>
Result
Wraps the raw HTTP response on success. Check Result.isSuccess to confirm the operation was accepted.
Example 
YouTube.addPlaylistToPlaylist("PLdestination", "PLsource").onSuccess {
    println("All tracks from source playlist added.")
}

​
YouTube.removeFromPlaylist

Removes a specific song entry from a playlist. Both the video ID and the set-video ID are required; the set-video ID uniquely identifies the entry when the same video appears multiple times. 
suspend fun removeFromPlaylist(
    playlistId: String,
    videoId: String,
    setVideoId: String,
): Result<*>
​
playlistId
String
required
The playlist to remove the song from.
​
videoId
String
required
The video ID of the song to remove.
​
setVideoId
String
required
The unique set-video ID for this playlist entry. Available as SongItem.setVideoId from a PlaylistPage or PlaylistContinuationPage response.
Return type
​
Result<*>
Result
Wraps the raw EditPlaylistResponse on success.
Example 
// song was obtained from YouTube.playlist("PLxxxxxxx")
YouTube.removeFromPlaylist(
    playlistId = "PLxxxxxxx",
    videoId = song.id,
    setVideoId = song.setVideoId!!,
).onSuccess {
    println("Song removed.")
}

​
YouTube.moveSongPlaylist

Moves a song to a different position in a playlist. Pass null for successorSetVideoId to move the song to the very end. 
suspend fun moveSongPlaylist(
    playlistId: String,
    setVideoId: String,
    successorSetVideoId: String?,
): Result<*>
​
playlistId
String
required
The playlist containing the song.
​
setVideoId
String
required
The set-video ID of the entry to move. Obtained from SongItem.setVideoId.
​
successorSetVideoId
String?
required
The set-video ID of the entry that should immediately follow the moved entry. Pass null to place the song at the end of the playlist.
Return type
​
Result<*>
Result
Wraps the raw EditPlaylistResponse on success.
Example 
// Move songA to the position immediately before songB
YouTube.moveSongPlaylist(
    playlistId = "PLxxxxxxx",
    setVideoId = songA.setVideoId!!,
    successorSetVideoId = songB.setVideoId,
)

// Move songA to the end
YouTube.moveSongPlaylist(
    playlistId = "PLxxxxxxx",
    setVideoId = songA.setVideoId!!,
    successorSetVideoId = null,
)
Sets a custom thumbnail image on a playlist using a two-step upload: first obtains an upload URL, uploads the image bytes, then links the resulting blob to the playlist. 
suspend fun uploadCustomThumbnailLink(
    playlistId: String,
    image: ByteArray,
): Result<String?>
​
playlistId
String
required
The playlist whose thumbnail will be changed.
​
image
ByteArray
required
Raw image bytes. JPEG is recommended. Recommended dimensions: 800 × 800 px.
Return type
​
Result<String?>
Result
On success, the new thumbnail URL returned by the edit-playlist response, or null if the URL could not be parsed.
Example 
val imageBytes = File("cover.jpg").readBytes()
YouTube.uploadCustomThumbnailLink("PLxxxxxxx", imageBytes).onSuccess { url ->
    println("Thumbnail updated: $url")
}

​
YouTube.removeThumbnailPlaylist

Removes the custom thumbnail from a playlist, reverting it to the auto-generated thumbnail. 
suspend fun removeThumbnailPlaylist(playlistId: String): Result<String?>
​
playlistId
String
required
The playlist to remove the custom thumbnail from.
Return type
​
Result<String?>
Result
The auto-generated thumbnail URL after removal, or null if parsing failed.
Example 
YouTube.removeThumbnailPlaylist("PLxxxxxxx").onSuccess {
    println("Custom thumbnail removed.")
}

Build docs developers (and LLMs) love

Get started for freeTalk to us