API Reference

Agents: fetch /llms.txt first. It is the machine-readable version of this page, with the exact calls for the common tasks.

Transcription is asynchronous, so the quickstart is four steps, not one: price it, create it (retry-safe and budget-capped), wait for it, then read the output you asked for. The three tabs are the same flow over three transports.

# 1. price it first (free, starts nothing)
curl -sS -X POST https://transcribe.so/api/v1/quotes \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'

# 2. create it: Idempotency-Key makes the retry safe,
#    max_charge_usd is the server-side ceiling (402 max_charge_exceeded above it)
curl -sS -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"source":"youtube","url":"https://youtu.be/dQw4w9WgXcQ","max_charge_usd":2}'

# 3. wait (bounded). Repeat while the body says "_timed_out": true
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/4821/wait?timeout=45"

# 4. read the transcript text (raw body, nothing truncated)
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/4821/transcript?format=txt&speaker_labels=true&timestamps=true"

# ...or a subtitle file for a video editor
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/4821/subtitles?format=srt" -o captions.srt

POST /quotes is free and starts nothing. Idempotency-Key makes step 2 safe to retry, and max_charge_usd is the server-side ceiling: if the computed charge is above it nothing is created and you get 402 max_charge_exceeded carrying both numbers. Step 3 holds the connection for up to 45 s per call and sets _timed_out: true when it has to return early, so you call it again. A webhook replaces step 3 entirely.

Everything below works from an agent runtime without a browser. Connect the runtime you already use, then four steps, in order.

Connect your runtime

Setup to first result

1. Set up. Create a key at /settings/api-keys (the Agent preset gives read + write with a monthly cap and an expiry), export it as TRANSCRIBE_API_KEY, and verify with GET /api/v1/me. For MCP clients: claude mcp add --transport http transcribe https://transcribe.so/mcp.
2. First transcript. The four-step quickstart above: quote, create with an Idempotency-Key and a max_charge_usd, wait, read.
3. The output you were asked for. The transcript itself is GET /transcript, a raw text/plain or text/markdown body. Beyond that, threedifferent things get called "captions", and they are three different endpoints:
   • Social post text — GET /timestamps, the caption or chapter list a human pastes into a post.
   • Timed subtitles — GET /subtitles, an SRT or VTT file for a player or editor.
   • Captioned video — POST /clips, a rendered MP4 with the captions burned in.
4. Who said what. GET /api/v1/search returns matching segments with speaker, start_ms, end_ms and a deep link.

Speaker labels are recording-local: SPEAKER_00 is the first voice in that recording, not an identified person, and speaker: null (rendered Unknown: in a text transcript) means the pipeline could not tell. Quote the matching segment, never a whole-section summary, when attributing a line to a speaker.

• Base URL: https://transcribe.so. Versioned prefix: /api/v1.
• Auth: every request carries Authorization: Bearer tsk_live_….
• Content type: JSON in, JSON out, UTF-8 — except the raw-body exports. /transcript and /subtitles return the file itself (text/plain, text/markdown, application/x-subrip, text/vtt) on success. Errors always keep the JSON envelope, on every endpoint.
• Identifiers: 4821 (plain integer) for transcriptions, tsk_live_… for API keys.
• Every response includes X-Request-Id. Quote it in support tickets.
• Rate limit: 60 requests / minute per key. Exceeded → 429 rate_limited.
• CORS: every /api/v1/* endpoint is open to any origin. Bearer auth, no cookies.
• Pricing: identical to /pricing. On subscription plans, transcription via the API is included ($0); Pay as you go bills the wallet at $1/hour.

The API authenticates with Bearer tokens on the Authorization header — API keys for scripts and integrations, no cookies. OAuth access tokens issued by the MCP connector flow are accepted on the same header and rate-limited per user rather than per key; the only difference is that webhook endpoints require an API key (OAuth tokens get 403 forbidden). Treat a key like a password.

Keys carry permissions and an optional monthly spend cap, both chosen when you create the key. Full access (default) can do everything; Read only keys are limited to GET endpoints and get 403 scope_forbidden on any POST/DELETE (they cannot create anything, including quotes and uploads; on /mcp they only see the read tools). A capped key stops starting transcription jobs, clip renders, and realtime sessions with 402 spend_cap_exceededonce the month's spend would pass the cap (a realtime session reserves its full 60-minute cap up front, so a monthly cap below one reserve blocks realtime entirely). OAuth tokens are always full access. GET /me echoes both under api_key.

Get a key

1. Sign in and visit /settings/api-keys.
2. Click Create key, give it a name (e.g. n8n-prod).
3. Copy the plaintext immediately — we show it once and never again. The server only stores sha256(key).

Smoke test

curl -sS https://transcribe.so/api/v1/me \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

Returns the authenticated user, current wallet balance, and plan tier.

Limits

• 20 active keys per user
• 60 requests / minute per key, on every plan
• On Pay as you go, the wallet is the spend cap; subscription plans meter processing minutes instead (below)

Per-plan processing limits

Enforced when you create a transcription — they never affect read endpoints:

• A file over your plan's length cap → 400 invalid_requestwith a message naming the cap. 12 h per file is the current pipeline maximum; your plan's cap from the table above applies first. Direct uploads are also bound by the 1 GB file-size cap; for longer high-bitrate files use a URL or YouTube source.
• Concurrent-job caps apply to subscription plans. On Pay as you go, the wallet is the effective limiter.
• Fair-use minutes are a hard wall on Pay as you go: exceeding the window → 429 rate_limited, same code as request throttling; the error.message says which wall you hit. Wait for the window to roll or upgrade.
• On subscription plans the fair-use figures are guidelines, not walls: jobs past them may queue at lower priority during peak hours, but are never rejected.

POST /api/v1/transcriptionsaccepts the same four sources as the dashboard's /transcriptions page. All four go through the same quote → wallet hold → enqueue path.

addons (string array, max 8) is accepted on POST /quotes and POST /transcriptions but rarely needed: speaker diarization is built into the standard pipeline, so omit it unless GET /api/v1/pipelines lists an add-on as compatible. Unknown codes return 400 addon_not_supported.

A URL to an Instagram caption

This is four calls, not two, and the fourth one can legitimately fail in a way that waiting will not fix. The sequence below is the one that actually works.

ID=$(curl -sS -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Idempotency-Key: ig-$(date +%F)-ep149" \
  -H "Content-Type: application/json" \
  -d '{"source":"youtube","url":"https://youtu.be/dQw4w9WgXcQ","max_charge_usd":2}' \
  | jq -r .id)

# bounded wait, repeated while "_timed_out": true
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/$ID/wait?timeout=45"

# the caption itself (social post text, no promotional footer)
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/$ID/timestamps?format=instagram_caption&variant=highlights"

# 409 not_ready with reason "artifact_missing" -> generate it, then repeat
curl -sS -X POST -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/$ID/timestamps/regenerate"

Quote first if the price matters (POST /quotes, free). Handle all five outcomes of the wait: queued or still processing (call wait again), completed (go on), failed and cancelled (stop; retrying re-charges from scratch), and the timeout, which is not a failure at all — it is _timed_out: true and means call again.

Swap format for x, threads or linkedin to target another platform. All four return social post text. If what you actually wanted was a subtitle file, that is /subtitles (try preset=instagram-reels); if it was a video with captions burned in, that is /clips.

Who said what, and when

curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/search?q=deferred%20revenue&limit=5" | jq '.hits[]'

# scope it to one recording
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/4821/search?q=deferred%20revenue"

Answer from the hit itself: its text is the quote, speaker is who said it, start_ms / end_ms is when, and url is the link that lands on the moment. A chapter or section summary is not evidence for a particular quote, and SPEAKER_01 is just the second voice in that recording, not a named person.

Every error response uses the same envelope:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Wallet balance too low. Top up your wallet at https://transcribe.so/billing.",
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://transcribe.so/billing"
  }
}

• message inlines an actionable URL where one applies. Terminal users see the link without parsing JSON.
• doc_url always points at a stable docs section or dashboard surface for that error.
• request_id is also returned as X-Request-Id on every response — quote it in support tickets.

Retry guidance

• 429: honour the retry-after header (seconds); if absent, back off 60s.
• 500: exponential backoff (1, 2, 4, 8s, max 60s), cap at 5 attempts. Use the same Idempotency-Key so duplicates don't bill twice.
• 402: do not retry until the user tops up.
• 409 not_ready: read reason. transcription_processing → honour Retry-After and retry the same call. artifact_missing → call POST /timestamps/regenerate, then retry. Not every 409 resolves by waiting.
• 402 max_charge_exceeded: nothing was created. Do not retry with a higher ceiling on your own — tell the user the real price and ask.
• 400 / 401 / 403 / 404: don't retry; fix the request. The video_private / video_unavailable / video_unavailable_probe / video_members_only / video_age_restricted codes are permanent for that URL — no request change will help (for the two gated codes, upload the file with source=upload).
• 503 probe_*: temporary failure on our side; honour the Retry-After header (seconds). Same Idempotency-Key is safe — 5xx responses are never cached.

POST endpoints accept an Idempotency-Keyheader. Use it on any request that creates or starts something, so retries don't double-bill or double-queue.

POST /api/v1/transcriptions
Idempotency-Key: 2026-04-30-podcast-ep-149

• First request runs normally. Subsequent requests with the same (principal, method, path, idempotency_key) within 24h return the original response unchanged. The principal is the API key, or the user plus client for an OAuth token — both auth types get the same protection, and two callers can never collide on one key.
• The path is part of the identity, so reusing one key across a quote and a create is not a replay: each path keeps its own entry and you never receive a quote where you expected a created job.
• Reusing the same key with a different body returns 400 invalid_request.
• 2xx and 4xx responses are cached; 5xx are not (so you can retry past transient bugs).
• Max key length: 128 chars. Use a UUID, content hash, or stable composite — anything that doesn't change across retries of the same logical request.

Transcriptions are async (~60s for 1-min audio, ~5min for an hour-long podcast). For long-running ops, ranked best-to-worst:

1. Webhook — best for fire-and-forget pipelines. Register one URL per API key, or pass callback_url on a single POST /transcriptions; we deliver an HMAC-signed transcription.completed POST when the job hits a terminal state. No connections held open, no rate-limit pressure, scales to any volume. Setup →
2. Long-poll /wait — best for synchronous "create-and-wait" flows where you can hold one HTTP connection. Server holds the response open up to timeout seconds (max 45) and returns as soon as the job finishes. One request per job.
   bashCopy

   curl -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
     "https://transcribe.so/api/v1/transcriptions/4821/wait?timeout=30&include=chapters,sections,qna"

3. Email notification — falls out automatically. Every user gets an email when their job completes. No code required.
4. Loop-polling GET /transcriptions/:id — don't. Naive polling every few seconds wastes tokens, eats rate limit, and gives you no faster signal than the long-poll. If your runtime can't hold a connection, use the webhook.

The synchronous endpoints (POST /timestamps/regenerate, POST /transcriptions) intentionally block until they have something to return; you don't poll those — you await the single response.

Get a signed POST when a transcription finishes — no polling. Two ways in: a registered webhook (one per API key, fires for every job the key starts) or a per-request callback_url on POST /transcriptions (fires for that one job; see below). Webhook endpoints are API-key only: OAuth bearer tokens (from the MCP connector flow) get 403 forbidden here, but they can still use callback_url.

Events

• transcription.completed — your transcription reached status: completed.
• transcription.failed — your transcription reached status: failed.
• clip.completed / clip.failed: a clip render created with this key finished; data.clip carries a fresh presigned mp4_url on completion.
• webhook.test — you called POST /api/v1/webhooks/test.

Register

curl -X POST https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/transcribe-so/webhook",
    "events": ["transcription.completed", "transcription.failed"]
  }'

events is optional and defaults to all four events (transcription.* and clip.*); unknown names are dropped (an empty result is 400 invalid_request). Registering again replaces the previous webhook on that key. The 201 response is { id, url, events, signing_secret, created_at } with a one-time signing_secret (whsec_…). Store it — we never show it again. You can also register a webhook from the dashboard at /settings/api-keys.

Inspect and remove

# Current webhook on this key (null if none)
curl -sS https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"
# -> { "webhook": { "id", "url", "events", "consecutive_failures", "disabled_at",
#                   "last_delivery_at", "last_success_at", "created_at" } }

# Revoke it
curl -sS -X DELETE https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"
# -> { "revoked": true }

Delivery headers

• Content-Type: application/json
• X-Transcribe-Signature: t=<unix-seconds>,v1=<hex> (see below)
• X-Transcribe-Event: transcription.completed (or transcription.failed, clip.completed, clip.failed, webhook.test)
• User-Agent: transcribe.so-webhook/1

Payload

{
  "id": "evt_1234",
  "event": "transcription.completed",
  "created": 1777472458,
  "data": {
    "transcription": {
      "id": 4821,
      "status": "completed",
      "stage": "completed",
      "pipeline_code": "standard",
      "language": "auto",
      "detected_language": "en",
      "source": "upload",
      "title": "podcast.mp3",
      "duration_seconds": 60,
      "charge_usd": 0.03,
      "error": null,
      "created_at": "2026-04-29T14:20:01.120Z",
      "processing_started_at": "2026-04-29T14:20:05.004Z",
      "completed_at": "2026-04-29T14:25:27.968Z"
    }
  }
}

transcription.failed carries the same shape with status: "failed" and a non-null error. webhook.test sends data: { message, delivered_at } instead.

Fetch the full result (segments, chapters, sections, qna) via GET /api/v1/transcriptions/:id/result?include=all— we don't push the full body inline because it can be large.

Verify the signature

Every delivery carries X-Transcribe-Signature: t=<unix-seconds>,v1=<hex>. The v1 value is hex(hmac_sha256(signing_secret, `$${t}.$${rawBody}`)). Verify on the raw body (re-serializing JSON breaks the HMAC).

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const m = header.match(/t=(\d+),v1=([0-9a-f]+)/);
  if (!m) return false;
  const [, t, v1] = m;
  // Reject if more than 5 minutes off (replay protection).
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === v1.length &&
    timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(v1, "utf8"));
}

import hmac, hashlib, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.match(r"t=(\d+),v1=([0-9a-f]+)", header)
    if not m: return False
    t, v1 = m.group(1), m.group(2)
    if abs(int(time.time()) - int(t)) > 300: return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

Retry

We retry any non-2xx (or network failure) at 1m, 5m, 30m, 3h, 12h. Five attempts max, 10s HTTP timeout each. After 5 consecutive failures across deliveries, the webhook itself is auto-disabled — re-enable it from the dashboard once your endpoint is healthy. Per-request callbacks have nothing to disable; each one just stops after its 5th attempt.

Per-request callback (callback_url)

Only care about one job, or calling through OAuth / the MCP server where you cannot register a webhook? Pass callback_url on POST /api/v1/transcriptions (or the MCP transcribe tool). The 202 then carries callback: { url, secret }; secret is the whsec_...HMAC key for that transcription's deliveries. It is deterministic per transcription (an idempotent replay returns the same value) and is never returned by GET, so store it.

curl -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "youtube",
    "url": "https://youtu.be/dQw4w9WgXcQ",
    "callback_url": "https://example.com/hooks/transcribe"
  }'
# 202 -> { "id": 4821, "status": "processing", ...,
#          "callback": { "url": "https://example.com/hooks/transcribe",
#                        "secret": "whsec_..." } }

• Same payload, headers and signature scheme as a registered webhook; only transcription.completed and transcription.failed are sent. POST /transcriptions/:id/clips takes a callback_url too (events clip.completed / clip.failed, secret returned as callback_secret).
• Fires in addition to a registered webhook when both apply (two deliveries).
• Must be a public http(s) URL (max 2048 chars). Private, loopback, link-local and internal hosts are rejected with 400 invalid_request, and the target is re-checked right before every POST.
• GET /transcriptions/:id echoes callback_url, never the secret.

Send a test event

curl -X POST https://transcribe.so/api/v1/webhooks/test \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

Enqueues a synthetic webhook.test delivery — useful to confirm your URL is reachable and signature verification works before any real transcriptions run.

Same rates as the dashboard, and no separate API quota or minimums. On subscription plans, transcriptions run on the included unlimited allowance ($0, no wallet hold). On Pay as you go, jobs bill the wallet at $1/hour. Captioned clip renders are a flat $0.05 per started 60 seconds of clip on every plan, billed to the wallet (held at request, settled on completion, released on failure).

Full upload flow with curl. The hardest path — YouTube and external URL skip steps 2-3.

For files over ~50 MB or unstable networks, see the resumable upload recipe instead. Same auth, same continuation step.

# 0. Smoke test
curl -sS https://transcribe.so/api/v1/me \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

# 1. Get a presigned upload URL
SIZE=$(stat -f%z podcast.mp3 2>/dev/null || stat -c%s podcast.mp3)
PRESIGN=$(curl -sS -X POST https://transcribe.so/api/v1/uploads \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"filename\": \"podcast.mp3\", \"content_type\": \"audio/mpeg\", \"file_size\": $SIZE }")
UPLOAD_URL=$(echo "$PRESIGN" | jq -r .upload_url)
UPLOAD_ID=$(echo "$PRESIGN" | jq -r .upload_id)

# 2. PUT the file straight to S3
curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @podcast.mp3

# 3. Submit the transcription
DURATION=$(ffprobe -i podcast.mp3 -show_entries format=duration -v quiet -of csv="p=0" | cut -d'.' -f1)
JOB=$(curl -sS -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"source\": \"upload\",
    \"upload_id\": \"$UPLOAD_ID\",
    \"original_filename\": \"podcast.mp3\",
    \"duration_seconds\": $DURATION
  }")
TR_ID=$(echo "$JOB" | jq -r .id)

# 4. Wait until done (long-poll, up to 45 s per call; loop while _timed_out)
while true; do
  STATE=$(curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID/wait?timeout=45" \
    -H "Authorization: Bearer $TRANSCRIBE_API_KEY")
  echo "$STATE" | jq -r '"\(.status) · \(.stage)"'
  S=$(echo "$STATE" | jq -r .status)
  [[ "$S" == "completed" || "$S" == "failed" ]] && break
done

# 5. Pull the result (segments are only included when you ask for them)
curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID/result?include=all" \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" | jq

Same flow in Python:

import os, time, requests

API = "https://transcribe.so/api/v1"
H = {"Authorization": f"Bearer {os.environ['TRANSCRIBE_API_KEY']}"}

with open("podcast.mp3", "rb") as f:
    body = f.read()

p = requests.post(f"{API}/uploads", headers=H, json={
    "filename": "podcast.mp3",
    "content_type": "audio/mpeg",
    "file_size": len(body),
}).json()

requests.put(p["upload_url"], data=body, headers={"Content-Type": "audio/mpeg"}).raise_for_status()

job = requests.post(f"{API}/transcriptions",
    headers={**H, "Idempotency-Key": "podcast-149"},
    json={
        "source": "upload",
        "upload_id": p["upload_id"],
        "original_filename": "podcast.mp3",
        "duration_seconds": 60,
    },
).json()

while True:
    state = requests.get(f"{API}/transcriptions/{job['id']}/wait", headers=H,
                         params={"timeout": 45}).json()
    if state["status"] in ("completed", "failed"):
        break

# Default include is chapters,sections,qna; ask for everything explicitly.
result = requests.get(f"{API}/transcriptions/{job['id']}/result", headers=H,
                      params={"include": "all"}).json()
print(f"segments={len(result['segments'])} chapters={len(result['chapters'])} sections={len(result['sections'])}")

Live speech-to-text over a WebSocket. The REST trio below mints a session and a short-lived ticket; the audio itself streams to ws_url. Sessions hold a 60-minute wallet quote up front (402 insufficient_funds if the wallet is short), allow one active session per user, and are gated behind the realtime pipeline (400 unsupported_pipeline when your plan doesn't include it). Not exposed over MCP.

{
  "session_id": "rts_0123456789abcdef",
  "transcription_id": 4822,
  "ws_url": "wss://api.transcribe.so/v1/realtime",
  "ticket": "…",
  "cap_minutes": 60,
  "language": "auto"
}

The same API is exposed as tools over the Model Context Protocol (server version 1.6.0) at https://transcribe.so/mcp (Streamable HTTP, stateless, POST-only). Auth is identical: send Authorization: Bearer tsk_live_…, or let the client run the OAuth 2.0 authorization-code + PKCE flow it discovers via /.well-known/oauth-protected-resource. Rate limit is shared with /api/v1 (60 requests / minute).

Connect

• Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → URL https://transcribe.so/mcp. Sign in when prompted (OAuth), or paste an API key as the Authorization header where the client supports it.
• Claude Code: claude mcp add --transport http transcribe https://transcribe.so/mcp, then /mcp to authenticate.
• ChatGPT: Settings → Connectors → Developer mode → add https://transcribe.so/mcp. The read-only search and fetch tools follow the ChatGPT connector contract, so the server also works for chat search and deep research.
• Codex: codex mcp add transcribe --url https://transcribe.so/mcp.
• Cursor: add the server to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global): {"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp"}}}. OAuth runs on first use.
• Gemini CLI: gemini mcp add --transport http transcribe https://transcribe.so/mcp, or the equivalent settings.json entry {"mcpServers":{"transcribe":{"httpUrl":"https://transcribe.so/mcp"}}}.
• Anything else: any MCP client that speaks Streamable HTTP. Tool schemas come from tools/list; discovery hints at /.well-known/mcp/server-card.json and /.well-known/mcp/server.json.

Tools

Every tool declares MCP annotations (title, readOnlyHint, destructiveHint) and returns one JSON text block plus structuredContent. Errors use the same { error: { code, message, request_id, doc_url } } envelope as REST. Registered webhooks, realtime sessions, tus uploads and addons are REST-only; the transcribe tool accepts callback_url for per-job notifications.

OAuth details

• Authorization server metadata: /.well-known/oauth-authorization-server (authorization code + PKCE S256, refresh tokens, dynamic client registration).
• Protected resource metadata: /.well-known/oauth-protected-resource (resource https://transcribe.so/mcp). Unauthenticated /mcp calls return 401 with a WWW-Authenticate header pointing there.
• OAuth tokens are rate-limited per user rather than per key and cannot manage webhooks. Plain-text guide for agents: /auth.md.

@transcribe-so/remotion (in the repo at packages/remotion/, private for now, zero runtime deps) wraps /words and /subtitles for Remotion projects: wordsToCaptions() maps the full word list (all: true) to @remotion/captions Caption[] (one caption per word, leading space on every token except the first, timestampMs = start_ms), chaptersToSequences() turns chapters into <Sequence> props, and useTranscribeWords() is a delayRender-aware hook for the case where the fetch has to happen inside the composition (returns status, words, captions, available, reason, error).

// Root.tsx: fetch outside the composition, pass words in as props
import { createClient } from '@transcribe-so/remotion'

export const calculateMetadata = async ({ props }) => {
  const client = createClient({ apiKey: process.env.TRANSCRIBE_API_KEY! })
  const { words } = await client.getWords(props.id, { all: true })
  return { props: { ...props, words } }
}

// TikTokCaptions.tsx: no fetch, no process.env
import { createTikTokStyleCaptions } from '@remotion/captions'
import { frameToMs, wordsToCaptions } from '@transcribe-so/remotion'
import type { TranscribeWord } from '@transcribe-so/remotion'
import { AbsoluteFill, useCurrentFrame, useVideoConfig } from 'remotion'
import { useMemo } from 'react'

export const TikTokCaptions: React.FC<{ id: number; words: TranscribeWord[] }> = ({ words }) => {
  const nowMs = frameToMs(useCurrentFrame(), useVideoConfig().fps)
  const { pages } = useMemo(
    () => createTikTokStyleCaptions({ captions: wordsToCaptions(words), combineTokensWithinMilliseconds: 1200 }),
    [words],
  )
  const page = pages.find((p) => nowMs >= p.startMs && nowMs < p.startMs + p.durationMs)
  return (
    <AbsoluteFill style={{ justifyContent: 'flex-end', alignItems: 'center', paddingBottom: 120 }}>
      <div style={{ fontSize: 64, color: 'white' }}>{page?.text}</div>
    </AbsoluteFill>
  )
}

Word timings exist only for word-timestamp pipelines: check available on /words first. Fetch in a script or calculateMetadata and pass words via inputProps; never read the API key from process.env inside a composition or bundle it into a public one. Full README, karaoke and chapters snippets: packages/remotion/README.md; a fetch-to-render recipe is in the cookbook.