If you're building something that needs the text of a YouTube video — a summariser, a search index, a research agent — you don't want to scrape captions by hand. Scribefy gives you two programmatic paths: a plain REST API for your own code, and an MCP server so AI assistants can fetch transcripts themselves.

Two ways to integrate

REST API — call it from any language. Good for backends, batch jobs, and data pipelines.
MCP server — scribefy-mcp on npm, speaking the Model Context Protocol. Drop it into Claude Desktop, Cursor, or Windsurf and the assistant pulls transcripts itself when a user pastes a link. See Build an AI workflow with Claude.

Both authenticate with the same API key and draw from the same credit balance.

Getting an API key

API keys are available on the API + MCP plan. Create one on your dashboard — you'll get a key like sk_live_… (or sk_test_… in test mode). It's shown once, so store it securely. Keys are sent as a bearer token.

REST: extract a transcript

curl -X POST https://api.scribefy.app/api/extract \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en"}'

The response is JSON with the metadata and the transcript split into timestamped segments:

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Example video",
  "channel": "Example channel",
  "durationSec": 213,
  "language": "en",
  "auto": false,
  "cached": false,
  "segments": [
    { "start": 0.0,  "text": "First line of the transcript." },
    { "start": 4.2,  "text": "Second line, a few seconds later." }
  ]
}

lang is optional (BCP-47, defaults to en). auto tells you whether the captions were auto-generated; cached tells you whether the call was free.

Credits and caching

A fresh extraction costs 1 credit (≤15 min) up to 8 credits (2 h+). But any transcript that's already been fetched — by you or anyone else — is served from a 30-day cache for free, with "cached": true. In practice, popular videos cost nothing, and re-fetching the same video never double-charges. New accounts get 2 free credits; see pricing.

Handling errors

Non-2xx responses return a JSON body with an error code you can switch on:

`error`	Meaning
`UNAUTHENTICATED`	Key invalid, revoked, or plan lapsed
`INSUFFICIENT_CREDITS`	Includes `balance` and `required`
`INVALID_URL`	Not a recognizable YouTube URL
`NO_CAPTIONS`	Video has no captions to extract
`LANG_UNAVAILABLE`	Requested language isn't available
`VIDEO_UNAVAILABLE`	Private, removed, or age-restricted
`BOT_CHECK` / `FETCH_FAILED`	Transient — retry shortly

The research endpoints (free)

Beyond extraction, three credit-free endpoints turn Scribefy into a research toolkit:

POST /api/search — { query, limit } → matching videos (title, channel, duration, views, URL).
POST /api/info — { url } → metadata + available caption tracks, without pulling the transcript.
POST /api/related — { url, limit } → YouTube's "Up next" feed.

A common pattern: search → info (to check captions) → extract only the videos you actually want.

MCP: zero-code integration

If your end user is working inside an AI assistant, skip the REST glue entirely. Add this to Claude Desktop's config:

{
  "mcpServers": {
    "scribefy": {
      "command": "npx",
      "args": ["-y", "scribefy-mcp"],
      "env": { "SCRIBEFY_API_KEY": "sk_live_…" }
    }
  }
}

Restart, and the assistant gains extract_transcript, search_videos, get_video_metadata, and get_related_videos. Cursor and Windsurf use the same package with their own config paths.

Frequently asked questions

What languages are supported?

Any caption language YouTube has for the video, human-authored or auto-generated. Pass a BCP-47 code in lang; omit it for English. Use /api/info to see which tracks exist first.

Is there a rate limit?

Usage is governed by your credit balance rather than a hard request cap. Cached fetches don't consume credits, so high-traffic apps that hit the same videos stay cheap.

Can I self-host or point at staging?

Set SCRIBEFY_API_BASE (defaults to https://api.scribefy.app) to target a different environment.

Ready to build? Grab a key on your dashboard and make your first call — or read how to get a transcript if you just need one by hand.