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.

InnerTube supports both unauthenticated (guest) and authenticated operation. Guest mode is the default and works for most read-only operations. Authenticated mode unlocks user-specific endpoints such as library management, history, and playlist editing.

​
Guest (Unauthenticated) Mode

No configuration is required to start using the library. By default, all calls are made without a session cookie and YouTube returns public content. Visitor data is an anonymous session token that improves response consistency and helps YouTube route requests correctly. You should refresh it on app startup: 
// Fetch and cache a fresh visitorData token
YouTube.refreshVisitorData()
refreshVisitorData() calls the InnerTube visitor endpoint, receives a new token, and stores it in YouTube.visitorData automatically. You can also read or write visitorData directly: 
// Persist visitorData across restarts
YouTube.visitorData = dataStore.get(VisitorDataKey)
To fully reset the guest identity — for example, during bot-detection rotation — call: 
YouTube.clearGuestSession()   // sets visitorData = null and dataSyncId = null
Guest mode supports: search, browse, album and artist pages, playlist pages, and the player endpoint.

​
Authenticated Mode

Authentication requires a raw YouTube session cookie string copied from a logged-in browser session. The cookie must contain at least SAPISID and __Secure-3PAPISID for the authorization hash to be computed correctly. 
YouTube.cookie = "SAPISID=xxxx; __Secure-3PAPISID=xxxx; SID=xxxx; HSID=xxxx; SSID=xxxx"
Setting cookie causes the library to parse it immediately into an internal map used for header construction. You must also provide dataSyncId, which is your account’s internal identifier. It is passed as onBehalfOfUser in the InnerTube request context and is required for browse and next calls to return personalised results: 
YouTube.dataSyncId = "your_data_sync_id_here"

​
SAPISID Authorization Header

InnerTube’s music endpoints require an Authorization header in the form SAPISIDHASH <timestamp>_<hash>. The library computes this automatically whenever a request is made with login enabled: 
Authorization: SAPISIDHASH 1700000000_<sha1(timestamp + SAPISID + origin)>
You do not need to compute or set this header yourself — it is generated per-request inside InnerTube.ytClient().

​
Forcing Login on Browse Requests

By default, browse calls only send the cookie on endpoints that explicitly opt in via setLogin = true. To force login headers on every browse request (useful for personalised home feeds), set: 
YouTube.useLoginForBrowse = true

​
What Requires Authentication

The following YouTube functions require a valid cookie and dataSyncId to return meaningful results or to succeed at all:
FunctionPurpose
YouTube.library(browseId)Read saved playlists, albums, and artists
YouTube.musicHistory()Listening history
YouTube.accountInfo()Display name and profile picture
YouTube.createPlaylist(title)Create a new playlist (blocking, returns playlist ID)
YouTube.deletePlaylist(playlistId)Delete a playlist
YouTube.renamePlaylist(playlistId, name)Rename a playlist
YouTube.addToPlaylist(playlistId, videoId)Add a song to a playlist
YouTube.removeFromPlaylist(playlistId, videoId, setVideoId)Remove a song from a playlist
YouTube.moveSongPlaylist(playlistId, setVideoId, successorSetVideoId)Reorder songs in a playlist
YouTube.likeVideo(videoId, like)Like (true) or unlike (false) a video
YouTube.likePlaylist(playlistId, like)Like (true) or unlike (false) a playlist
YouTube.subscribeChannel(channelId, subscribe)Subscribe (true) or unsubscribe (false) from an artist channel
YouTube.addSongToLibrary(videoId)Save a song to the library by video ID
YouTube.removeSongFromLibrary(videoId)Remove a song from the library by video ID
YouTube.uploadCustomThumbnailLink(playlistId, image)Upload a custom playlist thumbnail image (ByteArray)

​
Complete Setup Example

// Set credentials
YouTube.cookie = "SAPISID=xxxx; __Secure-3PAPISID=xxxx; SID=xxxx"
YouTube.dataSyncId = "your_data_sync_id"

// Restore visitorData from persistent storage (optional but recommended)
YouTube.visitorData = dataStore.get(VisitorDataKey)

// Confirm who is logged in
YouTube.accountInfo().onSuccess { account ->
    println("Logged in as: ${account.name}")
}

// Browse the user's library
YouTube.library("FEmusic_library_landing").onSuccess { page ->
    page.items.forEach { println(it.title) }
}

// Create a playlist (blocking call, returns the new playlist ID directly)
val playlistId: String? = YouTube.createPlaylist("My New Playlist")
println("Created playlist: $playlistId")

// Like a track
YouTube.likeVideo("dQw4w9WgXcQ", like = true).onSuccess {
    println("Video liked")
}
Raw YouTube cookies are sensitive session credentials. Anyone with access to your cookie string can act as you on YouTube. Store cookies encrypted — for example, using Android’s EncryptedSharedPreferences or EncryptedDataStore — and never log or transmit them in plaintext.

Build docs developers (and LLMs) love

Get started for freeTalk to us