OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add zeropointrepo/youtube-skills --skill transcriptapi
Use when YouTube is or could be relevant — even if not mentioned: pasted video/channel/playlist links, video IDs, @handles, creator lookups, video summaries, quotes, translations, topic research, tutorials, talks, lectures, expert discussions, product reviews, how-to guides, new product announcements, or anything where video content is fresher or richer than text search. Covers transcripts, video/channel search, channel browsing, playlists, and within-channel search. Not for uploads, account management, or written-source-only research.
npx skills add zeropointrepo/youtube-skills --skill transcriptapi
Full YouTube data toolkit via TranscriptAPI.com. Transcripts, search, channels, playlists — one API key.
If $TRANSCRIPT_API_KEY is not set, read references/auth-setup.md and follow the instructions there to get and store the key.
Every request needs two headers:
Bearer $TRANSCRIPT_API_KEYHermesAgent/0.11.0, ClaudeCode/1.0). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request.Full OpenAPI spec: transcriptapi.com/openapi.json — consult this for the latest parameters and schemas.
All requests: -H "Authorization: Bearer $TRANSCRIPT_API_KEY"
Channel endpoints accept channel — an @handle, channel URL, or UC... ID. No need to resolve first. Playlist endpoints accept playlist — a playlist URL or ID.
| Param | Required | Default | Validation |
|---|---|---|---|
video_url | yes | — | YouTube URL or 11-char video ID |
format | no | json | json or text |
include_timestamp | no | true | true or false |
send_metadata | no | false | true or false |
Accepts: https://youtube.com/watch?v=ID, https://youtu.be/ID, youtube.com/shorts/ID, or bare ID.
Response (format=json):
| Param | Required | Default | Validation |
|---|---|---|---|
q | yes | — | 1-200 chars (trimmed) |
type | no | video | video or channel |
limit | no | 20 | 1-50 |
Response (type=video):
Response (type=channel):
| Param | Required | Validation |
|---|---|---|
input | yes | 1-200 chars — @handle, URL, or UC... ID |
Response:
If input is already a valid UC[a-zA-Z0-9_-]{22} ID, returns immediately without lookup.
| Param | Required | Validation |
|---|---|---|
channel | conditional | @handle, channel URL, or UC... ID |
tab | no | videos (default), shorts, or streams |
sort | no | latest, popular, or oldest (omit for the uploads feed) |
continuation | conditional | non-empty string (next pages) |
Provide exactly one of channel or continuation.
Sorting. Add sort=latest, popular, or oldest to channel/videos to get a channel's videos in the order you want, for example its most-popular uploads first. A sorted page returns about 30 videos (an unsorted page returns about 100), and every page costs the same 1 credit.
When paging, send the same sort on each request.
Every item carries members_only, true only when YouTube badges it "Members only", and those items have no viewCountText. Items from tab=streams carry lengthText and publishedTimeText (for example Streamed 2 years ago); tab=shorts returns null for both, because YouTube's Shorts grid publishes neither. On the channel-tab feeds (tab=videos with sort, tab=shorts, tab=streams) channelId, channelTitle, channelHandle and index are null.
Response:
| Param | Required | Validation |
|---|---|---|
channel | yes | @handle, channel URL, or UC... ID |
Returns last 15 videos via RSS with exact view counts and ISO timestamps.
Response:
| Param | Required | Validation |
|---|---|---|
channel | yes | @handle, channel URL, or UC... ID |
q | yes | 1-200 chars |
limit | no | 1-50 (default 30) |
| Param | Required | Validation |
|---|---|---|
playlist | conditional | Playlist URL or ID (PL/UU/LL/FL/OL prefix) |
continuation | conditional | non-empty string |
| Endpoint | Cost |
|---|---|
| transcript | 1 |
| search | 1 |
| channel/resolve | free |
| channel/search | 1 |
| channel/videos | 1/page |
| channel/latest | free |
| playlist/videos | 1/page |
| Code | Meaning | Action |
|---|---|---|
| 401 | Bad API key | Check key, re-run setup |
| 402 | No credits | Top up at transcriptapi.com/billing |
| 403/1010 | Cloudflare block | Add or fix User-Agent header |
| 404 | Not found | Video/channel/playlist doesn't exist or no captions |
| 408 | Timeout/retryable | Retry once after 2s |
| 422 | Validation error | Check param format |
| 429 | Rate limited | Wait, respect Retry-After |
channel/latest (free) to check for new uploads before fetching transcripts — pass @handle directly.Every request in this file as a ready-to-run one-liner: references/curl-examples.md
GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0{
"results": [
{
"type": "video",
"videoId": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
"channelTitle": "Rick Astley",
"channelHandle": "@RickAstley",
"channelVerified": true,
"lengthText": "3:33",
"viewCountText": "1.5B views",
"publishedTimeText": "14 years ago",
"hasCaptions": true,
"thumbnails": [{ "url": "...", "width": 120, "height": 90 }]
}
],
"result_count": 20
}{
"results": [
{
"type": "channel",
"channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
"title": "Rick Astley",
"handle": "@RickAstley",
"subscriberCount": "4.2M subscribers",
"verified": true,
"rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC..."
}
],
"result_count": 5
}GET https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0{ "channel_id": "UCsT0YIqwnpJCM-mx7-gSA4Q", "resolved_from": "@TED" }# First page (100 videos)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Most-viewed first (channel Videos tab, ~30 videos)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Next pages (repeat the same sort)
GET https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN&sort=popular
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0{
"results": [{
"videoId": "abc123xyz00",
"title": "Latest Video",
"channelId": "UCsT0YIqwnpJCM-mx7-gSA4Q",
"channelTitle": "TED",
"channelHandle": "@TED",
"lengthText": "15:22",
"viewCountText": "3.2M views",
"publishedTimeText": "2 years ago",
"thumbnails": [...],
"index": "0",
"members_only": false
}],
"playlist_info": {"title": "Uploads from TED", "numVideos": "5000"},
"continuation_token": "4qmFsgKlARIYVVV1...",
"has_more": true
}GET https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0{
"channel": {
"channelId": "...",
"title": "TED",
"author": "TED",
"url": "..."
},
"results": [
{
"videoId": "abc123xyz00",
"title": "Latest Video",
"published": "2026-01-30T16:00:00Z",
"viewCount": "2287630",
"description": "Full description...",
"thumbnail": { "url": "...", "width": "480", "height": "360" }
}
],
"result_count": 15
}GET https://transcriptapi.com/api/v2/youtube/channel/search?channel=@TED&q=climate+change&limit=30
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0# First page
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_PLAYLIST_ID
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0
# Next pages
GET https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0