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.

InnerTube is a Kotlin Android library (com.metrolist.innertube) that wraps YouTube Music’s private InnerTube HTTP API hosted at https://music.youtube.com/youtubei/v1/. It provides a fully typed, coroutine-based interface for searching tracks, browsing artists and albums, resolving playback streams, managing playlists, and interacting with a user’s library — all without requiring an official Google API key.
InnerTube communicates directly with private YouTube Music endpoints. These are not part of any official Google API program and carry no stability guarantees. Google may change response schemas or access policies at any time.

​
Architecture

The library is built in two layers designed so most callers only ever need to touch the upper one. InnerTube — low-level HTTP client The InnerTube class owns the Ktor/OkHttp HTTP client and maps one-to-one with the raw InnerTube endpoints: search, browse, player, next, feedback, and more. Each method constructs the JSON request body (including context, client, and authentication headers) and returns the raw Ktor HttpStatement. You interact with this class directly only when building custom integrations. YouTube — high-level singleton API The YouTube Kotlin object holds a private InnerTube instance and exposes fully parsed, typed results as Kotlin Result<T> values. Every public method calls one or more InnerTube endpoints, deserializes the raw JSON response into domain model objects (pages, items, and continuations), and returns the result inside a runCatching wrapper. All configuration properties on YouTube (locale, cookie, proxy, etc.) are delegated transparently to the underlying InnerTube instance.

​
Key capabilities

  • Typed search — query songs, videos, albums, artists, playlists, podcasts, and episodes using SearchFilter constants.
  • Playback stream resolution — resolve audio/video streams for a given video ID with multi-client fallback across WEB_REMIX, IOS, ANDROID_VR, and embedded player clients.
  • Artist and album browsing — fetch complete ArtistPage and AlbumPage objects including biography, subscriber count, song lists, and related releases.
  • Playlist management — create, rename, delete, and edit playlists; add or remove individual tracks; reorder songs; upload custom thumbnails.
  • User library — browse liked songs, saved playlists, recently played items, and upload personal audio files.
  • Home, Explore, and Charts — load the personalised home feed, mood & genre categories, and regional chart sections.
  • Podcast support — browse podcast pages, fetch episode lists with continuation, and manage channel subscriptions.
  • PoToken / BotGuard support — pass a poToken string to YouTube.player() for clients that require it (WEB_REMIX, TVHTML5_SIMPLY).
  • Cipher deobfuscation — integrates with NewPipe Extractor for stream URL deobfuscation where needed.
  • Proxy support — route all HTTP traffic through any java.net.Proxy instance with optional base64 credentials.

​
Quick navigation

Quickstart

Add InnerTube to your Android project and make your first API call in a few minutes.

Configuration

Configure locale, authentication cookies, proxy settings, and network timeouts.

Build docs developers (and LLMs) love

Get started for freeTalk to us