# YouTubeSearch — full API reference

> Clean YouTube data for AI agents — search, transcripts, and summaries over one API, CLI, and MCP server, returned as agent-ready text.

Base URL: https://api-production-4a11e.up.railway.app
OpenAPI spec: https://api-production-4a11e.up.railway.app/v1/openapi.json
Human docs: https://youtubesearch-ai.vercel.app/docs

First call, no key needed (keyless serves search + already-cached content):

```bash
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/summary?sections=executive_summary"
```

## Authentication & tiers

Keyed requests send `Authorization: Bearer ys_live_...`. Get a free key at https://youtubesearch-ai.vercel.app/login (1,000 credits/month, no card). Requests without the header run on the keyless tier.

| Tier | Access | Rate | Credits/month |
|---|---|---|---|
| keyless (no header) | 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 |

Keyed responses carry `X-Credits-Charged` and `X-Credits-Remaining` headers. Check your balance free at `GET /v1/credits`.

## Credit costs

| Operation | Credits |
|---|---|
| POST /v1/search | 1 per query (batch: 1 × succeeded queries) |
| GET /v1/videos/{id} | 1 |
| GET /v1/videos/{id}/transcript | 1 cached · 2 cold · 10 when ASR transcribes |
| GET /v1/videos/{id}/summary | 1 cached · 5 cold |
| GET /v1/credits | 0 |

Charges apply on success only — errors are never billed.

## Endpoints

### POST /v1/search

Search YouTube. Works keyless. JSON body:

- `query` (string) — the search query; or `queries` (array of strings, max 5) to batch
- `limit` (integer, max 20) — results per query
- `filters` (object, optional) — `duration`, `recency`, `channel`

Results carry native metadata (title, channel, duration, views, age, thumbnails, description) plus a cached executive summary when the video has one.

```bash
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}'
```

### GET /v1/videos/{id}

Full metadata + chapters for one video. `{id}` is the 11-character YouTube video id.

```bash
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g" \
  -H "Authorization: Bearer ys_live_YOUR_KEY"
```

### GET /v1/videos/{id}/transcript

Every video returns a transcript — captions when they exist, ASR speech-to-text when they don't. Query parameters:

- `format` — `markdown` | `json` | `plain`
- `start`, `end` — return only the segment between these bounds
- `max_tokens` — cap the response size

```bash
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"
```

### GET /v1/videos/{id}/summary

Structured summary sections, selected per call. Query parameters:

- `sections` — comma-separated list of: executive_summary, key_points, detailed_summary, insights, timestamps, action_items, resources

```bash
curl -s "https://api-production-4a11e.up.railway.app/v1/videos/zjkBMFhNj_g/summary?sections=executive_summary,key_points" \
  -H "Authorization: Bearer ys_live_YOUR_KEY"
```

### GET /v1/credits

Balance for your key. Costs 0 credits.

```bash
curl -s "https://api-production-4a11e.up.railway.app/v1/credits" \
  -H "Authorization: Bearer ys_live_YOUR_KEY"
```

## Errors

Every error is the envelope `{"error": "CODE", "message": "..."}`.

| Status | Codes | Agent action |
|---|---|---|
| 400 | INVALID_REQUEST, INVALID_VIDEO_ID | Fix the request |
| 401 | INVALID_KEY, KEY_REQUIRED | Fix credentials (keyless 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/5xx are the retryable class) |

## MCP server

Remote Streamable HTTP endpoint exposing the four operations as read-only tools (`search_videos`, `get_video`, `get_transcript`, `get_summary`):

```bash
claude mcp add --transport http youtubesearch \
  https://mcp-production-f86c.up.railway.app/mcp \
  --header "Authorization: Bearer ys_live_YOUR_KEY"   # omit header for keyless
```

## CLI

```bash
npx youtubesearch auth login          # paste your key once
npx youtubesearch search "intro to large language models" --limit 5
npx youtubesearch video zjkBMFhNj_g
npx youtubesearch transcript zjkBMFhNj_g --max-tokens 2000
npx youtubesearch summary zjkBMFhNj_g --sections executive_summary,key_points
```