# YouTube Video Downloader — Full API Reference

Base URL: https://youtubedownloader.win

## Authentication

Two methods:
1. **Anonymous**: No auth header. Limited to 2 downloads/day, 720p, 200MB per video.
2. **Bearer token**: `Authorization: Bearer <token>`, issued when signing in on the site (email/password or Google). No separate CLI is available for this site.

Plans:
- Free (anonymous): 2 downloads/day, 720p, 200MB per video.
- Free (registered): 5 downloads/day, 720p, 200MB per video.
- Any credit purchase: raises the quality cap to 1080p for subsequent downloads.
- Lifetime SVIP: unlimited downloads at the highest available quality, never spends credits.

## Endpoints

### POST /api/download

Create a download task.

Request body (JSON):
- `url` (string, required): YouTube video URL (youtube.com or youtu.be)
- `filename` (string, optional): Custom output filename (SVIP only)
- `format` (string, optional): Custom ffmpeg format (SVIP only)
- `playlistIndex` (number, optional): Video index within a playlist (0-based)

Response 200:
```json
{
  "ok": true,
  "cached": false,
  "message": "download queued",
  "download": { "id": "uuid" },
  "video": { "id": "uuid", "status": "queued", "requestId": "uuid" },
  "remaining": 9
}
```

Response 429 (rate limited):
```json
{
  "ok": false,
  "error": "RATE_LIMIT",
  "plan": "free",
  "remaining": 0
}
```

Response 400:
```json
{
  "ok": false,
  "error": "EMPTY_URL" | "INVALID_URL_FORMAT" | "UNSUPPORTED_HOST"
}
```

### GET /api/downloads/{id}

Get download task details.

Response 200:
```json
{
  "ok": true,
  "task": {
    "id": "uuid",
    "url": "https://www.youtube.com/watch?v=...",
    "filename": "video.mp4",
    "status": "queued" | "running" | "done" | "failed",
    "created_at": "2026-01-01T00:00:00Z",
    "finished_at": "2026-01-01T00:01:00Z",
    "error_code": null,
    "file_size": 12345678,
    "duration": 120.5,
    "width": 1920,
    "height": 1080,
    "stage": "downloading" | "uploading" | null,
    "playlist_index": 0,
    "playlist_total": 1
  }
}
```

Status flow: `queued` → `running` → `done` | `failed`

### GET /api/file/{id}?dl=1

Get the video file. Returns 302 redirect to the file URL.

Response 302: Redirects to the file URL.
Response 409: `{"ok": false, "message": "Video not ready for download."}` — still processing.

### GET /api/downloads/{id}/transcript

Get the video's subtitles and plain-text transcript (free, no quota). Available once the
download is `done` and captions were found. Returns an empty array when the video has no captions.

Response 200:
```json
{
  "ok": true,
  "subtitles": [
    {
      "lang": "en",
      "kind": "manual" | "auto",
      "transcript": "Clean, timestamp-free text...",
      "srt": "1\n00:00:01,000 --> 00:00:04,000\n..."
    }
  ]
}
```

### GET /api/downloads

List user's downloads (requires auth).

Query params:
- `limit` (number, optional, default 50, max 200)

Response 200:
```json
{
  "ok": true,
  "items": [
    {
      "id": "uuid",
      "url": "https://www.youtube.com/watch?v=...",
      "status": "done",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

### DELETE /api/downloads/{id}

Delete a download record. Cannot delete running tasks.

Response 200: `{"ok": true, "message": "deleted"}`
Response 409: `{"ok": false, "error": "cannot delete running task"}`

### GET /api/user/usage

Get today's usage (requires auth).

Response 200:
```json
{
  "ok": true,
  "used": 3,
  "limit": 10,
  "remaining": 7,
  "plan": "free"
}
```

For SVIP users, `limit` and `remaining` are -1 (unlimited).

### GET /api/user/subscription

Get subscription / plan info.

Response 200:
```json
{
  "ok": true,
  "plan": "free" | "svip",
  "subscription": {
    "status": "active",
    "cancelAtPeriodEnd": false,
    "currentPeriodEnd": 1735689600
  }
}
```

## Typical AI Agent Workflow

1. `POST /api/download` with the YouTube video URL
2. Poll `GET /api/downloads/{id}` every 5 seconds until `status === "done"`
3. `GET /api/file/{id}?dl=1` to get the download URL (302 redirect)
4. Optionally `GET /api/downloads/{id}/transcript` for subtitles and a text transcript

## Error Codes

- `EMPTY_URL`: No URL provided
- `INVALID_URL_FORMAT`: URL doesn't start with http(s)
- `UNSUPPORTED_HOST`: Only youtube.com and youtu.be are supported
- `RATE_LIMIT`: Daily download limit reached
- `FILE_SIZE_LIMIT`: Video exceeds the plan's file size limit

## MCP Server

No MCP server is available for this site yet. Call the REST API above directly, using a
bearer token or session cookie obtained by signing in on the website.