Documentation
One API, CLI, and MCP server over the same four operations — search, metadata, transcripts, summaries. Everything below is copy-paste runnable against production.
First call in under a minute
No signup needed for the first call — keyless requests serve search and already-cached content. This one returns the executive summary of a cached video:
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/summary?sections=executive_summary"
To fetch fresh, uncached content, get a free API key — 1,000 credits a month, no card — and pass it as a bearer token:
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/transcript?format=markdown&max_tokens=300" \-H "Authorization: Bearer ys_live_YOUR_KEY"
replace ys_live_YOUR_KEY with your key
One header, three tiers
Keyed requests send Authorization: Bearer ys_live_… — nothing else. Requests without the header run on the keyless tier.
| Tier | Access | Rate | Credits/month |
|---|---|---|---|
keyless | cached content only + search | 10 searches/hr, 60 reads/hr per IP | — |
free | everything | 2 req/s | 1,000 |
pro | everything | 10 req/s | 20,000 |
Every keyed response carries X-Credits-Charged and X-Credits-Remaining headers. Charges apply on success only — errors are never billed. Per-call costs are listed with each endpoint below.
Four operations. No fifth flaky one.
POST /v1/search
Search YouTube and get agent-ready results. Works keyless.
JSON body
| Parameter | Description |
|---|---|
query | string — the search query. Send queries (array, up to 5) instead to batch. |
limit | integer, up to 20 — results per query. |
filters | object, optional — duration, recency, channel. |
curl -s -X POST https://api-production-4a11e.up.railway.app/v1/search \-H "Authorization: Bearer ys_live_YOUR_KEY" \-H "Content-Type: application/json" \-d '{"query": "intro to large language models", "limit": 3}'
Returns a result list per query: title, channel, duration, views, age, thumbnails, description — plus a cached executive summary when the video has one. Batch calls return one list per query.
1 credit per query · batch: 1 × succeeded queries
GET /v1/videos/{id}
Full metadata for one video — the cheap look before an expensive extract.
Path
| Parameter | Description |
|---|---|
id | the 11-character YouTube video id. |
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g" \-H "Authorization: Bearer ys_live_YOUR_KEY"
Returns the video's native metadata — title, channel, duration, views, publish date, description — with chapters when the video has them.
1 credit
GET /v1/videos/{id}/transcript
Every video returns a transcript — captions when they exist, speech-to-text when they don't.
Query parameters
| Parameter | Description |
|---|---|
format | markdown | json | plain — the shape of the returned text. |
start, end | return only the segment between these bounds. |
max_tokens | cap the response size to fit your context budget. |
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/transcript?format=markdown&max_tokens=300" \-H "Authorization: Bearer ys_live_YOUR_KEY"
Returns the timestamped transcript in the requested format. Sourced from captions when available; otherwise ASR transcribes the audio — no captions ≠ no answer.
1 cached · 2 cold · 10 when ASR transcribes
GET /v1/videos/{id}/summary
Structured summary sections you select per call — take only the tokens you need.
Query parameters
| Parameter | Description |
|---|---|
sections | comma-separated list of: executive_summary, key_points, detailed_summary, insights, timestamps, action_items, resources. |
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/summary?sections=executive_summary" \-H "Authorization: Bearer ys_live_YOUR_KEY"
Returns only the sections you asked for, as structured text.
1 cached · 5 cold
GET /v1/credits
The balance for your key. Takes no parameters.
curl -s "https://api-production-4a11e.up.railway.app/v1/credits" \-H "Authorization: Bearer ys_live_YOUR_KEY"
0 credits — checking your balance is always free
Typed, never silent
Every error is the same envelope — a machine-readable code your agent can branch on, plus a human-readable message:
{"error": "KEY_REQUIRED","message": "This video's transcript isn't cached yet. Keyless access serves cached content only — get a free API key (1,000 credits/month, no card) to fetch fresh content."}
| Status | Codes | Agent action |
|---|---|---|
400 | INVALID_REQUEST, INVALID_VIDEO_ID | Fix the request. |
401 | INVALID_KEY, KEY_REQUIRED | Fix credentials — a keyless request hit uncached content. |
402 | OUT_OF_CREDITS | Monthly allowance exhausted; resets at month start. |
403 / 404 | AGE_RESTRICTED, TRANSCRIPTS_DISABLED, VIDEO_UNAVAILABLE, … | Video-state facts; don't retry. |
429 | RATE_LIMITED | Honor Retry-After. |
502 / 503 | *_FAILED, *_UNAVAILABLE | Transient; retry. 429 and 5xx are the retryable class. |
Failed calls are never billed.
Wire it into Claude Code
A remote Streamable HTTP server exposes the four operations as read-only tools: search_videos, get_video, get_transcript, get_summary.
claude mcp add --transport http youtubesearch \https://mcp-production-f86c.up.railway.app/mcp \--header "Authorization: Bearer ys_live_YOUR_KEY"
omit --header to run keyless (cached content + search only)
The same four operations, from a shell
No install — npx youtubesearch runs the latest version. Log in once; keyless works without it.
npx youtubesearch auth login # paste your key oncenpx youtubesearch search "intro to large language models" --limit 5npx youtubesearch video zjkBMFhNj_gnpx youtubesearch transcript zjkBMFhNj_g --max-tokens 2000npx youtubesearch summary zjkBMFhNj_g --sections executive_summary,key_points
The machine-readable contract
Every endpoint, parameter, and response shape above is specified in the OpenAPI document — feed it to a generator or an agent:
https://api-production-4a11e.up.railway.app/v1/openapi.json
Agents can also read /llms-full.txt — this entire reference as one plain-markdown file.