# youtube2text.org API - complete reference for agents and developers

Base URL: `https://youtube2text.org`

The service extracts transcripts from YouTube videos and returns them as plain text.
Two interfaces are available: a REST API and an MCP (Model Context Protocol) server.
Source code: https://github.com/dm-nosov/youtube2text.

## Authentication - three ways, pick one

### 1. Demo key (no account, start here)

    GET https://youtube2text.org/api/demo-key

Response: `{"success": true, "apiKey": "yt_..."}`. Use this key in the `x-api-key`
header. The demo key shares a monthly per-IP quota (5 videos/month per IP). When you
get `RATE_LIMIT_EXCEEDED`, switch to option 2 or 3.

### 2. Your own API key

Sign in with Google at https://youtube2text.org/app/keys and create a key.
Free plan: 5 videos/month. Paid plans: basic 50/mo, pro 500/mo, unlimited.

### 3. MCP with OAuth (recommended for Claude and MCP clients)

Add `https://youtube2text.org/mcp` as a custom connector / MCP server. The server
implements OAuth 2.1 with dynamic client registration (RFC 7591), PKCE (S256), and
discovery metadata (RFC 8414 / RFC 9728). Clients like claude.ai handle the whole
flow automatically: you sign in with Google and click Allow. Usage counts against
your youtube2text account plan.

## REST API

### Transcribe a video

    GET https://youtube2text.org/api/transcribe?url=<YOUTUBE_URL>&maxChars=5000
    x-api-key: <YOUR_KEY>

or

    POST https://youtube2text.org/api/transcribe
    x-api-key: <YOUR_KEY>
    Content-Type: application/json

    {"url": "https://www.youtube.com/watch?v=VIDEO_ID", "maxChars": 5000}

`Authorization: Bearer <YOUR_KEY>` is accepted as an alternative to `x-api-key`.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| url | string | yes | Any YouTube URL form (watch, youtu.be, embed) or a bare 11-character video id |
| maxChars | number | no | Truncate the transcript to this many characters (default and max: 150000) |

Success response (HTTP 200):

    {"result": {"videoId": "...", "title": "...", "pubDate": "2025-01-01T00:00:00-07:00",
                "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Error response shape (all errors):

    {"error": {"code": "<ERROR_CODE>", "message": "...", "status": 401,
               "docsUrl": "https://youtube2text.org/api.md", "retryAfterSeconds": 3600}}

Error codes:

| Code | HTTP | Meaning / what to do |
|------|------|----------------------|
| UNAUTHORIZED | 401 | Missing/invalid key. Get one: GET /api/demo-key |
| VALIDATION_ERROR | 400 | Missing url parameter |
| INVALID_URL | 400 | Not a recognizable YouTube URL |
| VIDEO_NOT_FOUND | 404 | Video does not exist |
| TRANSCRIPT_UNAVAILABLE | 404 | Video has no captions/transcript |
| RATE_LIMIT_EXCEEDED | 429 | Quota exhausted; retryAfterSeconds tells you when to retry. Upgrade or create an account for more |
| YOUTUBE_ERROR | 500 | Upstream YouTube failure; retry later |

`/api/youtubeTranscribe` is a legacy alias of `/api/transcribe` (same params).

## MCP server

Endpoint: `https://youtube2text.org/mcp` (streamable HTTP, stateless).
Auth: OAuth 2.1 (see above) or an API key as `Authorization: Bearer <key>` / `x-api-key`.

Tool: `transcribe_video`

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| url | string | yes | YouTube URL |
| maxChars | number | no | 1..150000 |

Returns structured content: `{title, content, contentSize, videoId, pubDate, truncated}`.

### claude.ai (web/desktop)

Settings -> Connectors -> Add custom connector -> URL `https://youtube2text.org/mcp` ->
complete the Google sign-in consent. Done.

### Claude API

    {"type": "url", "url": "https://youtube2text.org/mcp", "name": "youtube2text",
     "authorization_token": "<YOUR_API_KEY>"}

Use this object in the `mcp_servers` array of a Messages API request.

### OpenAI Responses API

    {"type": "mcp", "server_label": "youtube2text",
     "server_url": "https://youtube2text.org/mcp",
     "headers": {"x-api-key": "<YOUR_KEY>"}, "require_approval": "never"}

## OAuth discovery (for MCP client implementers)

- `GET /.well-known/oauth-protected-resource` - resource metadata (RFC 9728)
- `GET /.well-known/oauth-authorization-server` - AS metadata (RFC 8414)
- `POST /oauth/register` - dynamic client registration (RFC 7591), public clients, PKCE S256 required
- `GET /oauth/authorize`, `POST /oauth/token` - authorization code + refresh token grants

## Quotas

| Plan | Price | Videos/month |
|------|-------|--------------|
| demo key | free, no account | 5 per IP |
| free account | free | 5 |
| basic | $5.99/mo | 50 |
| pro | $9.99/mo | 500 |
| unlimited | $19.99/mo | unlimited |