Documentation

API Reference

All endpoints require an API key via Authorization: Bearer ytt_sk_... header unless noted otherwise.

POST/api/transcripts

Transcribe a YouTube video. Returns the transcript immediately for caption-only, or 202 with a job ID for Whisper/Gemini jobs.

Request body

{ "url": "https://youtube.com/watch?v=...", "lang": "en" }

Query params

?format=text — returns plain text instead of JSON

Responses

200/201Transcript returned (sync)

202Job queued (async, poll for result)

401Missing or invalid auth

402Quota exceeded or Whisper required (upgrade)

429YouTube rate limit

GET/api/transcripts

List your transcripts. Supports search via ?q= parameter.

Query params

?q=search+term

Responses

200Array of transcript summaries

401Missing or invalid auth

GET/api/transcripts/:id

Get a single transcript by ID. Use for polling async jobs.

Responses

200Transcript (status: done) or job status (status: processing)

401Missing or invalid auth

404Not found

GET/api/health

Health check. No auth required.

Responses

200{ "status": "ok" }