Documentation Index
Fetch the complete documentation index at: https://rocks.docs.rive.wtf/llms.txt
Use this file to discover all available pages before exploring further.
Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.
Use the endpoint paths below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.
Quick Start
Get a channel ID or username
Find the target channel’s ID (starts with UC…) or legacy username.
Call the desired route
Use /api/youtube/channel, /api/youtube/video, or any other route below.
Use the response data
Parse the returned JSON for stats, metadata, video lists, playlists, and more.
Good for Discord bots, dashboards, stat trackers, and any app that needs YouTube data without managing OAuth.
Channel
Get full channel info including statistics, description, and branding.
Endpoint
Query Parameters
YouTube channel ID (starts with UC…). Required if username is not provided.
Legacy YouTube username. Required if channel_id is not provided.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/channel?channel_id=UCBR8-60-B28hp2BmDPdntcQ" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/channel?channel_id=UCBR8-60-B28hp2BmDPdntcQ', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'channel_id': 'UCBR8-60-B28hp2BmDPdntcQ'}
response = requests.get('https://rocks.rive.wtf/api/youtube/channel', headers=headers, params=params)
print(response.json())
Example Response
{
"id": "UCBR8-60-B28hp2BmDPdntcQ",
"snippet": {
"title": "YouTube",
"description": "The YouTube channel for ...",
"customUrl": "@youtube",
"publishedAt": "2005-04-23T00:00:00Z",
"country": "US",
"thumbnails": {
"default": { "url": "https://yt3.ggpht.com/...", "width": 88, "height": 88 },
"high": { "url": "https://yt3.ggpht.com/...", "width": 800, "height": 800 }
}
},
"statistics": {
"viewCount": "9000000000",
"subscriberCount": "95000000",
"hiddenSubscriberCount": false,
"videoCount": "700"
}
}
Video
Get full metadata, statistics, and content details for a single video.
Endpoint
Query Parameters
YouTube video ID (e.g. dQw4w9WgXcQ).
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/video?video_id=dQw4w9WgXcQ" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/video?video_id=dQw4w9WgXcQ', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'video_id': 'dQw4w9WgXcQ'}
response = requests.get('https://rocks.rive.wtf/api/youtube/video', headers=headers, params=params)
print(response.json())
Example Response
{
"id": "dQw4w9WgXcQ",
"snippet": {
"title": "Rick Astley - Never Gonna Give You Up",
"channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
"channelTitle": "Rick Astley",
"publishedAt": "2009-10-25T06:57:33Z",
"tags": ["rick astley", "never gonna give you up"],
"categoryId": "10"
},
"statistics": {
"viewCount": "1400000000",
"likeCount": "16000000",
"commentCount": "2200000"
},
"contentDetails": {
"duration": "PT3M33S",
"definition": "hd",
"caption": "true"
},
"status": {
"privacyStatus": "public",
"embeddable": true,
"madeForKids": false
}
}
Search
Search YouTube globally for videos, playlists, or channels.
Endpoint
Query Parameters
Comma-separated result types. Options: video, playlist, channel.
order
string
default:"relevance"
Sort order. Options: relevance, date, rating, viewCount, title.
Number of results to return. Max 50.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/search?q=lofi+hip+hop&type=video&order=viewCount&max_results=10" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/search?q=lofi+hip+hop&max_results=10', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'q': 'lofi hip hop', 'type': 'video', 'order': 'viewCount', 'max_results': 10}
response = requests.get('https://rocks.rive.wtf/api/youtube/search', headers=headers, params=params)
print(response.json())
Example Response
{
"count": 10,
"results": [
{
"kind": "youtube#searchResult",
"id": { "kind": "youtube#video", "videoId": "jfKfPfyJRdk" },
"snippet": {
"title": "lofi hip hop radio 📚 - beats to relax/study to",
"channelTitle": "Lofi Girl",
"publishedAt": "2020-02-22T07:00:05Z",
"description": "..."
}
}
]
}
Playlists
Get all public playlists for a channel.
Endpoint
GET /api/youtube/playlists
Query Parameters
Number of playlists to return. Max 50.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/playlists?channel_id=UCBR8-60-B28hp2BmDPdntcQ" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/playlists?channel_id=UCBR8-60-B28hp2BmDPdntcQ', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'channel_id': 'UCBR8-60-B28hp2BmDPdntcQ'}
response = requests.get('https://rocks.rive.wtf/api/youtube/playlists', headers=headers, params=params)
print(response.json())
Example Response
{
"count": 3,
"playlists": [
{
"id": "PLbpi6ZahtOH6Ar_3GPy3ghR8EVNtNQ5pX",
"snippet": {
"title": "YouTube Spotlight",
"description": "The best of YouTube.",
"channelTitle": "YouTube",
"publishedAt": "2012-11-01T21:00:00Z"
},
"contentDetails": { "itemCount": 42 }
}
]
}
Playlist Items
Get all videos inside a specific playlist.
Endpoint
GET /api/youtube/playlist/items
Query Parameters
YouTube playlist ID (starts with PL…).
Number of items to return.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/playlist/items?playlist_id=PLbpi6ZahtOH6Ar_3GPy3ghR8EVNtNQ5pX&max_results=25" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/playlist/items?playlist_id=PLbpi6ZahtOH6Ar_3GPy3ghR8EVNtNQ5pX', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'playlist_id': 'PLbpi6ZahtOH6Ar_3GPy3ghR8EVNtNQ5pX', 'max_results': 25}
response = requests.get('https://rocks.rive.wtf/api/youtube/playlist/items', headers=headers, params=params)
print(response.json())
Example Response
{
"count": 25,
"items": [
{
"id": "PLbpi6ZahtOH6Ar_3GPy3ghR8EVNtNQ5pX_abc123",
"snippet": {
"title": "Some Video Title",
"position": 0,
"channelTitle": "YouTube",
"resourceId": { "kind": "youtube#video", "videoId": "abc123xyz" }
},
"contentDetails": {
"videoId": "abc123xyz",
"videoPublishedAt": "2023-06-01T12:00:00Z"
}
}
]
}
Get top-level comment threads for a video.
Endpoint
GET /api/youtube/comments
Query Parameters
Number of comment threads to return. Max 100.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/comments?video_id=dQw4w9WgXcQ&max_results=20" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/comments?video_id=dQw4w9WgXcQ&max_results=20', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'video_id': 'dQw4w9WgXcQ', 'max_results': 20}
response = requests.get('https://rocks.rive.wtf/api/youtube/comments', headers=headers, params=params)
print(response.json())
Example Response
{
"count": 20,
"comments": [
{
"id": "UgxA1B2C3D4E5F6G7H8",
"snippet": {
"videoId": "dQw4w9WgXcQ",
"totalReplyCount": 12,
"topLevelComment": {
"id": "UgxA1B2C3D4E5F6G7H8",
"snippet": {
"textDisplay": "This never gets old.",
"authorDisplayName": "SomeUser",
"likeCount": 4200,
"publishedAt": "2021-01-01T00:00:00Z"
}
}
}
}
]
}
All Data
Fetch a full channel data dump in one call — channel info, all uploaded videos, playlists, and recent search results.
Endpoint
Query Parameters
YouTube channel ID. Required if username is not provided.
Legacy YouTube username. Required if channel_id is not provided.
Maximum number of uploaded videos to include.
Example Request
curl -X GET "https://rocks.rive.wtf/api/youtube/all?channel_id=UCBR8-60-B28hp2BmDPdntcQ&max_videos=50" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/youtube/all?channel_id=UCBR8-60-B28hp2BmDPdntcQ&max_videos=50', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'channel_id': 'UCBR8-60-B28hp2BmDPdntcQ', 'max_videos': 50}
response = requests.get('https://rocks.rive.wtf/api/youtube/all', headers=headers, params=params)
print(response.json())
Example Response
{
"fetched_at": "2026-04-23T12:00:00Z",
"channel": { "id": "UCBR8-60-B28hp2BmDPdntcQ", "snippet": { "title": "YouTube" }, "statistics": { "subscriberCount": "95000000" } },
"uploads_playlist_id": "UUBR8-60-B28hp2BmDPdntcQ",
"videos": [ { "id": "abc123", "snippet": { "title": "Some Video" }, "statistics": { "viewCount": "500000" } } ],
"playlists": [ { "id": "PLxxx", "snippet": { "title": "Featured" }, "contentDetails": { "itemCount": 10 } } ],
"search_results": [ { "id": { "videoId": "xyz789" }, "snippet": { "title": "Another Video" } } ]
}
Endpoint Summary
| Method | Endpoint | Description |
|---|
| GET | /api/youtube/channel | Channel info and statistics |
| GET | /api/youtube/video | Single video metadata and stats |
| GET | /api/youtube/search | Global search for videos, playlists, channels |
| GET | /api/youtube/playlists | All public playlists for a channel |
| GET | /api/youtube/playlist/items | All videos inside a playlist |
| GET | /api/youtube/comments | Top-level comment threads for a video |
| GET | /api/youtube/all | Full channel data dump |
All endpoints require Authorization: Bearer YOUR_API_KEY in the request header.
