Where to Find Invidious API Documentation: Complete Guide to Endpoints and Source Code

The official Invidious API documentation is hosted at docs.invidious.io/api/, with the underlying source code located in the src/invidious/routes/api/v1/ directory and routing definitions in src/invidious/routing.cr.

The Invidious API provides a privacy-focused alternative to YouTube's official API, allowing developers to fetch video metadata, channel information, and manage user data programmatically. This guide covers exactly where to find both the public Invidious API documentation and the source code implementation in the iv-org/invidious repository.

Official Documentation Location

The canonical reference for the Invidious API lives on the project's documentation site at docs.invidious.io/api/. This markdown-based documentation is maintained in the separate iv-org/documentation repository, specifically within the [docs/api.md](https://github.com/iv-org/documentation/blob/master/docs/api.md) file.

Source Code Structure and API Implementation

While the documentation site provides human-readable guides, the ultimate source of truth for the API specification resides in the Crystal source code. The implementation follows a layered architecture that defines routes, handlers, and response formats.

Routing Table and Endpoint Registration

All public API endpoints are registered in src/invidious/routing.cr (lines 244-332). This file maps URL patterns like /api/v1/videos/:id to their respective handler functions, establishing the contract between incoming HTTP requests and the application's response logic.

Video and Channel Endpoints

• Video metadata: Handled in src/invidious/routes/api/v1/videos.cr, which constructs JSON payloads for endpoints including captions, storyboards, and transcripts.
• Channel data: Defined in src/invidious/routes/api/v1/channels.cr, covering routes such as /api/v1/channels/:id/latest and playlist listings.

Authenticated Routes

User-specific actions requiring authentication—such as managing playlists, subscriptions, and notifications—are implemented in src/invidious/routes/api/v1/authenticated.cr. These endpoints require bearer tokens obtained through the /api/v1/auth/tokens endpoint.

Response Serialization

The shape of API responses is determined by JSON serializers located in src/invidious/jsonify/api_v1/. Key files include:

• video_json.cr: Structures video metadata responses
• channel_json.cr: Defines channel data formats

Request Filtering

API traffic filtering and exclusion rules are managed in src/invidious/helpers/handlers.cr (lines 24-66), which contains middleware specifically for /api/v1/* routes.

Practical API Usage Examples

Fetching Video Metadata

Retrieve public video information using the /api/v1/videos/:id endpoint:

curl https://invidious.snopyta.org/api/v1/videos/9bZkp7q19f0?pretty=1

The pretty=1 parameter returns formatted JSON for debugging purposes.

Accessing Channel Data via Crystal

Programmatically fetch a channel's latest videos using Crystal's HTTP client:

require "http/client"
require "json"

BASE_URL = "https://invidious.snopyta.org"

def channel_latest(ucid : String)
  url = "#{BASE_URL}/api/v1/channels/#{ucid}/latest"
  resp = HTTP::Client.get(url)
  raise "Failed" unless resp.success?
  JSON.parse(resp.body)
end

# Example: UC_x5XG1OV2P6uZZ5FSM9Ttw is Google's channel ID

latest = channel_latest("UC_x5XG1OV2P6uZZ5FSM9Ttw")
puts latest["videos"].as_a.map(&.["title"]).join("\n")

Performing Searches

Query the search endpoint with region parameters:

curl "https://invidious.snopyta.org/api/v1/search?q=crystal+programming&region=US&pretty=1"

Authenticated Playlist Management

Add videos to authenticated playlists using bearer tokens (endpoint defined at lines 308-309 in authenticated.cr):

TOKEN="YOUR_API_TOKEN"
PLAYLIST_ID="PL1234567890abcdef"
VIDEO_ID="dQw4w9WgXcQ"

curl -X POST "https://invidious.snopyta.org/api/v1/auth/playlists/${PLAYLIST_ID}/videos" \
     -H "Authorization: Bearer $TOKEN" \
     -d "video_id=$VIDEO_ID"

Summary

• Official docs: Find human-readable guides at docs.invidious.io/api/, sourced from the iv-org/documentation repository.
• Routing logic: All API routes are registered in src/invidious/routing.cr (lines 244-332).
• Video endpoints: Implemented in src/invidious/routes/api/v1/videos.cr with serializers in src/invidious/jsonify/api_v1/video_json.cr.
• Channel data: Handled in src/invidious/routes/api/v1/channels.cr.
• Authenticated actions: Require tokens and are processed in src/invidious/routes/api/v1/authenticated.cr.
• Middleware: Traffic filtering occurs in src/invidious/helpers/handlers.cr (lines 24-66).

Frequently Asked Questions

Is the Invidious API free to use without authentication?

Yes, most read-only endpoints such as video metadata, channel information, and search are accessible without authentication. However, user-specific actions like managing playlists, subscriptions, or accessing notifications require authentication via bearer tokens obtained from /api/v1/auth/tokens.

How do I discover all available API endpoints in the source code?

The definitive list of available endpoints resides in src/invidious/routing.cr between lines 244-332. This file contains the routing table that maps every HTTP path to its handler function, serving as the authoritative registry of the API surface area.

What format does the Invidious API return?

The API returns JSON responses structured by serializers in src/invidious/jsonify/api_v1/. Video responses follow the schema defined in video_json.cr, while channel data conforms to channel_json.cr, ensuring consistent data structures across all endpoints.

Where can I report inaccuracies in the API documentation?

Since the documentation site sources its content from the iv-org/documentation repository, you should open issues or pull requests in that repository rather than the main Invidious codebase. The specific file governing API documentation is docs/api.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}