# getvideotranscript for agents

Turns a YouTube URL or video ID into a timestamped transcript. Optional AI cleaning. Cached when already fetched.

This file is the agent guide. Humans can read the HTML API page; the facts are the same.

## Base URL

https://getvideotranscript.com

Prefer this host. Identify yourself with a descriptive User-Agent.

## Auth

Most videos need an API key. The demo id `dQw4w9WgXcQ` is open so you can try the endpoint. Request a key: support@getvideotranscript.com.

- Query: `?api_key=YOUR_TOKEN`
- Header: `Authorization: Bearer YOUR_TOKEN`
- JSON body: `"api_key": "YOUR_TOKEN"`

## Check cache

GET /api/cache/{video_id}

## Extract a transcript

GET /api/youtube?url={YOUTUBE_URL}&api_key=YOUR_TOKEN
GET /api/youtube?video_id={ID}&clean=true&api_key=YOUR_TOKEN
POST /api/youtube

Either `url` or `video_id` is required. `clean=true` runs AI cleanup when available.

## Permalink formats

- HTML: /youtube/{video_id}
- Markdown: /youtube/{video_id}?format=md
- JSON: /youtube/{video_id}?format=json

## Other endpoints

- GET /api/health — liveness
- GET /api — endpoint index
- GET /AGENTS.md — this file

## Status codes

| Code | Meaning |
|---|---|
| 200 | Transcript returned |
| 400 | Missing or invalid url / video_id — do not retry |
| 401 | Missing or invalid API key — do not retry |
| 404 | No transcript — do not retry |
| 500 | Server error — back off |

## Etiquette

- Cache-check first when you already have a video id.
- Do not retry 400, 401, or 404. Those will not change.
- On 500, back off exponentially.
- YouTube URLs only on /api/youtube. File upload is the HTML form, not this API.