API Documentation

Quick Start

1

Get API Key

Register an account and create an API key from your dashboard or via the API.

2

Make Requests

Authenticate with Bearer token or X-API-Key header on every request.

3

Transcribe Videos

POST a YouTube URL to /v1/transcribe and get a full transcript back.

Authentication

All API endpoints require authentication via one of two methods:

Bearer Token (JWT)

Obtain a JWT by logging in via POST /auth/login. Include it in the Authorization header.

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

API Key

Create an API key via POST /keys. Include it in the X-API-Key header.

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "X-API-Key: yttr_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

Rate Limits

Rate limits depend on your subscription plan. Exceeding limits returns HTTP 429.

Plan	Requests/hour	Daily minutes	Monthly minutes
Free	5	15	300
Starter	30	100	5,000
Pro	120	300	15,000
Max	300	500	Unlimited

Endpoints

POST /v1/transcribe

Submit a YouTube video for transcription. Returns a job immediately (async) or waits for the result (sync).

Request Body

Field	Type	Required	Description
`url`	string	Yes	YouTube video URL
`async_mode`	boolean	No	If true, returns immediately with a job_id for polling. Default: false

Example

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "X-API-Key: yttr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

Response (sync)

json

{
  "job_id": "abc123",
  "status": "completed",
  "video_title": "Rick Astley - Never Gonna Give You Up",
  "duration_seconds": 213,
  "segments": [
    {"start": 0.0, "end": 4.5, "text": "We're no strangers to love..."}
  ],
  "full_text": "We're no strangers to love..."
}

Response (async_mode: true)

json

{
  "job_id": "abc123",
  "status": "processing"
}

GET /v1/jobs

List your transcription jobs, paginated.

Query Parameters

Field	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max 100)
`status`	string	—	Filter by status: processing, completed, failed

bash

curl https://yt2txt.com/v1/jobs?page=1&per_page=10 \
  -H "X-API-Key: yttr_your_key"

GET /v1/jobs/{job_id}

Retrieve details of a specific job. Use this to poll async jobs until status is "completed" or "failed".

bash

curl https://yt2txt.com/v1/jobs/abc123 \
  -H "X-API-Key: yttr_your_key"

POST /v1/jobs/{job_id}/actions/{action}

Run AI post-processing on a completed transcript.

Available Actions

Action	Description
`summarize`	Generate a concise summary of the transcript
`chapters`	Create timestamped chapters
`keywords`	Extract key topics and keywords
`translate`	Translate the transcript
`quiz`	Generate quiz questions from the content

Example

bash

curl -X POST https://yt2txt.com/v1/jobs/abc123/actions/summarize \
  -H "X-API-Key: yttr_your_key"

Response

json

{
  "action": "summarize",
  "result": "This video covers the classic 1987 hit..."
}

POST /auth/register

Create a new user account.

Request Body

json

{
  "email": "[email protected]",
  "password": "your_secure_password"
}

POST /auth/login

Authenticate and receive a JWT token.

Request Body

json

{
  "email": "[email protected]",
  "password": "your_secure_password"
}

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

POST /keys

Create a new API key. Requires Bearer token authentication.

Request Body

json

{
  "name": "my-integration"
}

Response

json

{
  "id": "key_abc123",
  "name": "my-integration",
  "key": "yttr_abc123...",
  "created_at": "2026-03-17T12:00:00Z"
}

GET /keys

List all your API keys (key values are masked).

DELETE /keys/{key_id}

Revoke an API key. This action cannot be undone.

MCP Server

An AI agent can drive yt2txt directly over the Model Context Protocol. The server is at https://yt2txt.com/mcp, it speaks streamable HTTP, and it reads your API key from the X-API-Key header. A tool call does exactly what the same key can do over the REST API, and costs the same minutes, so API access on the Pro and Max plans is what an agent needs too.

Client configuration

Add the server to your MCP client's configuration file. This is the Claude Code form, in .mcp.json; replace the placeholder with a key of your own.

json

{
  "mcpServers": {
    "yt2txt": {
      "type": "http",
      "url": "https://yt2txt.com/mcp",
      "headers": {
        "X-API-Key": "yttr_your_key"
      }
    }
  }
}

From the command line

One command writes the same entry, if your client has a command line of its own.

bash

claude mcp add --transport http yt2txt https://yt2txt.com/mcp \
  --header "X-API-Key: yttr_your_key"

Tools

Tool	Description
`transcribe`	Start transcribing a YouTube video and return its job id.
`get_job`	Report a job's status: pending, processing, completed, failed or cancelled.
`get_transcript`	Read a completed job's transcript, at most 50,000 characters per call.
`run_action`	Run an AI action on a completed transcript: summarize, translate, chapters, keywords or quiz.
`get_balance`	Report the plan and the minutes and credits left on the key's account.

Ask the agent for a transcript and it calls transcribe, polls get_job until the status is completed, then reads the text with get_transcript, following next_offset until it is null. A refused call comes back as one line saying what would change the answer, and a transcription is charged when the job starts work, exactly as it is over the REST API.

Error Handling

Every error carries the same body: an error object, under detail, with a code and a message.

json

{
  "detail": {
    "error": {
      "code": "QUOTA_EXCEEDED",
      "message": "No minutes or credits left. Add credits or change plan."
    }
  }
}

Branch on detail.error.code, never on the message: code is stable, and the message is translated and may be reworded. The one exception is a request that fails validation, in its body, query or path: it answers 422 with a detail array naming the offending fields.

Status Code	Description
`400`	Bad Request — invalid parameters or missing required fields
`401`	Unauthorized — missing or invalid authentication
`403`	Forbidden — insufficient permissions or quota exceeded
`404`	Not Found — resource does not exist
`422`	Unprocessable Entity — validation error in request body
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — unexpected failure

Interactive Explorer

Try out the API directly from your browser using Swagger UI. Authenticate with your token to make live requests.

Scroll down or click to load the API Explorer