API reference

Use this reference for REST endpoints, parameters and responses. Open the interactive reference (Swagger UI) at https://api.transcript1.com/v1/docs, or download the machine-readable OpenAPI document from https://api.transcript1.com/v1/openapi.json.

Base URL and conventions

The base URL is https://api.transcript1.com/v1.

• Request and response bodies are JSON with snake_case field names.
• Timestamps are ISO 8601 in UTC, for example 2026-10-13T09:30:00.000Z.
• Durations and transcript times are in seconds.
• Every error uses the same envelope. See Errors.
• Every response to an authenticated request carries X-RateLimit-Limit and X-RateLimit-Remaining. See Billing and limits.

Authentication

Send a credential in the Authorization header:

curl https://api.transcript1.com/v1/account \
  -H "Authorization: Bearer t1_..."

• An API key starts with t1_. Create one on the API keys page. API keys can call every endpoint.
• An OAuth access token starts with t1o_. MCP clients such as Claude and ChatGPT receive one when you connect them. OAuth tokens carry the scopes transcriptions:read and transcriptions:write.

A token without the required scope returns 403 insufficient_scope. A missing or invalid credential returns 401 unauthorized. For chunk uploads, authenticate PUT /v1/transcriptions/:id/upload/chunks/:index with the X-Upload-Token returned when you create the upload. See Uploads.

Endpoints

Create a transcription

POST /v1/transcriptions takes one of three body forms:

1. A platform URL as JSON. The only platform is youtube:

   {
     "platform": "youtube",
     "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
     "source": "auto",
     "language": "auto",
     "diarize": false,
     "webhook_url": "https://example.com/hook"
   }

2. A one-shot file upload as multipart/form-data, up to 95 MB.

3. A chunked upload reservation as JSON, for files up to 2 GB:

   { "upload": { "filename": "interview.m4a", "size": 48210334, "mime_type": "audio/mp4" } }

source, language, diarize and webhook_url are optional in every form. See Sources and options, Uploads and Webhooks. An account needs a verified email address and some usable minutes to create a transcription.

Query parameters

reuse_recent=true returns your team's most recent transcription of the same video (different URL forms of one video match) with the same source, language and diarize, created in the last 24 hours and not failed or canceled. The response carries "reused": true. If nothing matches, a new transcription is created and the response carries "reused": false. The flag is rejected with invalid_request for uploads and when combined with webhook_url. An Idempotency-Key replay takes precedence over it. Two simultaneous first requests can still create two transcriptions, so use the flag for sequential retries.

Idempotency-Key header

Send Idempotency-Key as a request header on POST /v1/transcriptions to make a retry safe. It is not a query parameter. The value is 1 to 255 characters:

curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Idempotency-Key: 6f1c2d9e-3b7a-4a55-9c1e-0d2f8a7b4c10" \
  -H "Content-Type: application/json" \
  -d '{"platform":"youtube","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Repeating a request with the same key and the same parameters returns the original transcription and does not charge again. The same key with different parameters returns 409 idempotency_conflict. For chunked uploads, repeating the create with the same key issues a fresh upload token.

Status codes

• 201 means the transcription is awaiting_upload and the response includes the upload block.
• 202 means the transcription is processing (queued, fetching or transcribing).
• 200 means it reached a final status within wait: completed, failed or canceled. A video transcript1 has already processed can complete immediately and return 200.
• Errors use the codes in Errors, for example 402 insufficient_minutes, 409 idempotency_conflict, 413 media_too_large, 422 invalid_request and 429 rate_limited.

Get a transcription

GET /v1/transcriptions/:id returns the transcription object. A completed transcription includes transcript. An unknown id, or an id that belongs to another team, returns 404 not_found.

Rendered formats return the transcript itself, not JSON:

• text is text/plain: one line per segment, with a Speaker 1: style prefix when speakers were identified.
• srt is application/x-subrip: one cue per segment.
• vtt is text/vtt: a WEBVTT file with one cue per segment, using <v Speaker 1> voice tags when speakers were identified.

The status code depends on the format. With format=json the response is always 200, so read status in the body. With a rendered format, a completed transcription returns the rendered body with 200. While the transcription is still queued, fetching or transcribing, you get the JSON object back with 202. A failed or canceled transcription returns its JSON object with 200. Rendered formats are only produced when the transcription is completed.

List transcriptions

GET /v1/transcriptions lists your team's transcriptions, newest first, without transcripts.

{
  "object": "list",
  "data": [ { "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD", "object": "transcription", "status": "completed" } ],
  "next_cursor": null
}

next_cursor is null on the last page. Each item in data is a full transcription object, shortened here.

Cancel or delete a transcription

DELETE /v1/transcriptions/:id returns 204. What it does depends on the status:

• A transcription that is awaiting_upload, queued, fetching or transcribing is canceled and any minutes already charged for it are refunded.
• A completed, failed or canceled transcription is deleted together with its stored transcript. The record stays and is returned only when you pass include_deleted=true.

Upload endpoints

Use these three endpoints for chunked uploads. See Uploads for step-by-step instructions.

• PUT /v1/transcriptions/:id/upload/chunks/:index sends one chunk as application/octet-stream. It is authenticated by the X-Upload-Token header, not by a bearer credential. It returns { "object": "upload_chunk", "index": 0, "size": 8388608 }.
• GET /v1/transcriptions/:id/upload returns received_chunks, uploaded_bytes, total_bytes, the planned chunks and expires_at, so an interrupted upload can resume.
• POST /v1/transcriptions/:id/upload/complete checks that every planned chunk arrived, assembles the file and queues the transcription. It returns 202 with the transcription object, or 409 with upload_incomplete and missing_chunks.

Get your account

GET /v1/account returns your plan, usable minutes and limits without charging minutes.

{
  "object": "account",
  "user": { "id": "5b0e6c1c-0d6f-4c1f-9b5e-8f3f4d0a7a11", "email": "[email protected]" },
  "plan": { "id": "9d4e0c0a-2b8a-4f0c-8d63-6a8d3c8a1f22", "name": "Monthly" },
  "minutes": {
    "remaining": 1180,
    "cycle": 980,
    "topup": 200,
    "topup_usable": true,
    "resets_at": "2026-11-13T09:30:00.000Z"
  },
  "renews_at": "2026-11-13T09:30:00.000Z",
  "limits": { "requests_per_minute": 200, "max_active_jobs": 10 }
}

plan is null when the team has no plan. See Billing and limits for what each minutes field means.

The transcription object

Every endpoint that returns a transcription uses this shape. POST responses add reused, and the response that reserves a chunked upload adds upload.

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "completed",
  "source": { "platform": "youtube", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "media_id": "dQw4w9WgXcQ" },
  "media": { "title": "Example video", "author": "Example channel", "duration_seconds": 212 },
  "options": { "source": "auto", "language": "auto", "diarize": false },
  "transcript_source": "youtube_captions",
  "caption_kind": "auto_generated",
  "language": "en",
  "billed_minutes": 4,
  "cached": false,
  "error": null,
  "created_at": "2026-10-13T09:30:00.000Z",
  "completed_at": "2026-10-13T09:30:04.000Z",
  "deleted_at": null,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "speakers": [],
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." },
      { "start": 4.2, "end": 9.8, "speaker": null, "language": "en", "text": "Today we are looking at how transcripts are made." }
    ]
  }
}

Segment times are seconds from the start of the media.