Skip to main content

Documentation Index

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

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

The Playlists API covers reading playlist content as well as creating, editing, and deleting playlists and their tracks. Read operations work without authentication; all mutation methods require a valid YouTube.cookie.
Cookie authentication is required for all write/mutation methods: createPlaylist(), renamePlaylist(), deletePlaylist(), addToPlaylist(), addPlaylistToPlaylist(), removeFromPlaylist(), moveSongPlaylist(), uploadCustomThumbnailLink(), removeThumbnailPlaylist(), likeVideo(), likePlaylist(), subscribeChannel(), addSongToLibrary(), removeSongFromLibrary(), and toggleSongLibrary(). Set the cookie before calling any of these methods:
YouTube.cookie = "SAPISID=...; ..."

​
YouTube.playlist()

Fetches a playlist page including header metadata, songs, and related playlists. 
suspend fun playlist(playlistId: String): Result<PlaylistPage>
​
playlistId
String
required
The playlist ID (without the VL prefix). Example: "PLxxxxxxxxxxxxxxxx".

​
Returns

Result<PlaylistPage>
​
playlist
PlaylistItem
Playlist header metadata.
​
songs
List<SongItem>
First page of tracks. Each SongItem carries a setVideoId field needed for mutation operations.
​
songsContinuation
String?
Continuation token for loading more tracks via playlistContinuation().
​
continuation
String?
Continuation token for loading additional related content sections.
​
related
List<YTItem>?
Related playlists, albums, or artists surfaced in the right-hand column.

​
YouTube.playlistContinuation()

Fetches the next page of tracks for a playlist. 
suspend fun playlistContinuation(continuation: String): Result<PlaylistContinuationPage>
​
continuation
String
required
Continuation token from PlaylistPage.songsContinuation or a previous PlaylistContinuationPage.continuation.

​
Returns

Result<PlaylistContinuationPage>
​
songs
List<SongItem>
Next page of tracks.
​
continuation
String?
Token for the following page. null when all tracks have been loaded.

​
YouTube.createPlaylist()

Creates a new empty playlist and returns its ID. 
fun createPlaylist(title: String): String
​
title
String
required
Display name for the new playlist.

​
Returns

String — the newly created playlist ID (e.g. "PLxxxxxxxxxxxxxxxx").
createPlaylist() is a blocking function implemented with runBlocking. Call it from a background thread or coroutine dispatcher that supports blocking — never from the main thread.

​
YouTube.renamePlaylist()

Renames an existing playlist. 
suspend fun renamePlaylist(playlistId: String, name: String): Result<Unit>
​
playlistId
String
required
The ID of the playlist to rename.
​
name
String
required
The new display name.

​
Returns

Result<Unit> — succeeds silently on success.

​
YouTube.deletePlaylist()

Permanently deletes a playlist. 
suspend fun deletePlaylist(playlistId: String): Result<Unit>
​
playlistId
String
required
The ID of the playlist to delete.

​
Returns

Result<Unit> — succeeds silently on success.

​
YouTube.addToPlaylist()

Adds a single video to a playlist. 
suspend fun addToPlaylist(playlistId: String, videoId: String): Result<Unit>
​
playlistId
String
required
The target playlist ID.
​
videoId
String
required
The video ID to add.

​
Returns

Result<Unit>

​
YouTube.addPlaylistToPlaylist()

Appends all tracks from one playlist into another. 
suspend fun addPlaylistToPlaylist(playlistId: String, addPlaylistId: String): Result<Unit>
​
playlistId
String
required
The target playlist ID.
​
addPlaylistId
String
required
The source playlist whose tracks will be copied in.

​
Returns

Result<Unit>

​
YouTube.removeFromPlaylist()

Removes a specific track from a playlist using both the video ID and its playlist-level setVideoId. 
suspend fun removeFromPlaylist(
    playlistId: String,
    videoId: String,
    setVideoId: String,
): Result<Unit>
​
playlistId
String
required
The playlist to remove from.
​
videoId
String
required
The video ID of the track to remove.
​
setVideoId
String
required
The per-occurrence unique identifier for this track within the playlist. Obtain from SongItem.setVideoId returned by playlist() or playlistContinuation(). This is not the same as videoId — a track that appears twice in a playlist has two different setVideoId values.

​
Returns

Result<Unit>

​
YouTube.moveSongPlaylist()

Moves a track to a new position within a playlist by specifying which track it should appear before. 
suspend fun moveSongPlaylist(
    playlistId: String,
    setVideoId: String,
    successorSetVideoId: String?,
): Result<Unit>
​
playlistId
String
required
The playlist containing the track to move.
​
setVideoId
String
required
The setVideoId of the track being moved.
​
successorSetVideoId
String?
The setVideoId of the track that the moved track should appear before. Pass null to move the track to the end of the playlist.

​
Returns

Result<Unit>

​
Thumbnail Management

Uploads a custom JPEG/PNG thumbnail for a playlist. 
suspend fun uploadCustomThumbnailLink(
    playlistId: String,
    image: ByteArray,
): Result<String?>
​
playlistId
String
required
The playlist ID.
​
image
ByteArray
required
Raw image bytes (JPEG or PNG recommended). The implementation performs a two-stage upload: first an initiating request that returns a GUploader upload ID, then the actual blob upload.
Returns: Result<String?> — the new thumbnail URL on success, or null if the response header doesn’t contain one.

​
YouTube.removeThumbnailPlaylist()

Removes the custom thumbnail from a playlist, reverting to the auto-generated one. 
suspend fun removeThumbnailPlaylist(playlistId: String): Result<String?>
​
playlistId
String
required
The playlist ID.
Returns: Result<String?> — the resulting thumbnail URL (the auto-generated one), or null.

​
Social Actions

​
YouTube.likeVideo()

Likes or unlikes a video. 
suspend fun likeVideo(videoId: String, like: Boolean): Result<Unit>
​
videoId
String
required
The video ID.
​
like
Boolean
required
true to like, false to unlike.

​
YouTube.likePlaylist()

Saves or unsaves a playlist to the authenticated user’s library. 
suspend fun likePlaylist(playlistId: String, like: Boolean): Result<Unit>
​
playlistId
String
required
The playlist ID.
​
like
Boolean
required
true to save, false to unsave.

​
YouTube.subscribeChannel()

Subscribes to or unsubscribes from a YouTube channel. 
suspend fun subscribeChannel(channelId: String, subscribe: Boolean): Result<Unit>
​
channelId
String
required
The channel ID (obtainable from ArtistItem.channelId).
​
subscribe
Boolean
required
true to subscribe, false to unsubscribe.

​
Library Song Management

​
YouTube.addSongToLibrary()

Adds a song to the authenticated user’s library by fetching fresh feedback tokens via next(). 
suspend fun addSongToLibrary(videoId: String): Result<Boolean>
​
videoId
String
required
The video ID of the song to add.
Returns: Result<Boolean> — true when the feedback endpoint confirms the action was processed.

​
YouTube.removeSongFromLibrary()

Removes a song from the authenticated user’s library. Uses fresh tokens from next() for reliability. 
suspend fun removeSongFromLibrary(videoId: String): Result<Boolean>
​
videoId
String
required
The video ID of the song to remove.
Returns: Result<Boolean>

​
YouTube.toggleSongLibrary()

Convenience wrapper that adds or removes a song based on the addToLibrary flag. 
suspend fun toggleSongLibrary(videoId: String, addToLibrary: Boolean): Result<Boolean>
​
videoId
String
required
The video ID.
​
addToLibrary
Boolean
required
true to add, false to remove.

​
YouTube.feedback()

Low-level feedback endpoint. Send one or more opaque feedback tokens to trigger server-side actions (e.g. library add/remove, history removal). 
suspend fun feedback(tokens: List<String>): Result<Boolean>
​
tokens
List<String>
required
Feedback tokens. Obtain SongItem.libraryAddToken and SongItem.libraryRemoveToken from search, browse, or next results.
Returns: Result<Boolean> — true when all feedback responses report isProcessed = true.

​
Example: Create a playlist and add songs

import com.music.innertube.YouTube
import kotlinx.coroutines.runBlocking

// Authentication is required
YouTube.cookie = "SAPISID=...; ..."

// 1. Create a new playlist (blocking call — run on background thread)
val playlistId = YouTube.createPlaylist("My Favourites")
println("Created playlist: $playlistId")

// 2. Add individual songs
YouTube.addToPlaylist(playlistId, "dQw4w9WgXcQ").getOrThrow()
YouTube.addToPlaylist(playlistId, "9bZkp7q19f0").getOrThrow()

// 3. Load the playlist to inspect tracks and setVideoIds
val page = YouTube.playlist(playlistId).getOrThrow()
println("Tracks in playlist:")
page.songs.forEach { song ->
    println("  ${song.title} — setVideoId=${song.setVideoId}")
}

// 4. Remove the first song using its setVideoId
val first = page.songs.first()
first.setVideoId?.let { svid ->
    YouTube.removeFromPlaylist(playlistId, first.id, svid).getOrThrow()
    println("Removed: ${first.title}")
}

// 5. Move the second song to the end
val second = page.songs.getOrNull(1)
second?.setVideoId?.let { svid ->
    YouTube.moveSongPlaylist(playlistId, svid, successorSetVideoId = null).getOrThrow()
    println("Moved to end: ${second.title}")
}

// 6. Like a video and subscribe to an artist channel
YouTube.likeVideo("dQw4w9WgXcQ", like = true).getOrThrow()
YouTube.subscribeChannel("UCiMhD4jzUqG-IgPzUmmytRQ", subscribe = true).getOrThrow()

Build docs developers (and LLMs) love

Get started for freeTalk to us