Tube Operator: API and MCP

Back to the app

Your YouTube library (transcripts, breakdowns, followed channels), accessible programmatically and wired into Claude or Cursor through the built-in MCP server.

Authentication

Every request carries a personal API key in the X-Api-Key header. Keys are created and revoked in the app, under Settings > API and MCP (Pro plan only). Each key is displayed in plain text only once, when it is created: store it in a secrets manager.

curl https://youtube.tagbuilder.dev/api/videos \
  -H "X-Api-Key: ytr_your_key"

API base URL: https://youtube.tagbuilder.dev. Responses are JSON (UTF-8). An invalid or revoked key returns 401. Paid actions consume the account's credits, just like in the app (insufficient balance: 402).

Main endpoints

Videos

Endpoint	Description
GET`/api/videos`	Lists the videos in your library (id, title, author, status, whether a breakdown has been generated).
GET`/api/videos/{id}`	Details for one video: metadata, `transcript`, `restitution`, `action_plan`.
POST`/api/videos`	Archives a video. JSON body: `{"url": "https://www.youtube.com/watch?v=..."}`. With `"mode": "transcript"`, only the transcript is fetched (1 credit); without it, the breakdown is generated right away and streamed as plain text (response header `X-Video-Id`). Option `"quality": "standard" \| "max"`.
POST`/api/videos/{id}/restitution`	Generates (or regenerates) the breakdown of an archived video. Optional body `{"quality": "max"}`. Response streamed as plain text.
POST`/api/videos/{id}/action-plan`	Generates the video's summary + action plan (the first generation is included in the video's credit). Streamed response.
DELETE`/api/videos/{id}`	Removes a video from your library.

Followed channels

Endpoint	Description
GET`/api/channels`	Lists followed channels (id, title, video count, number already fetched).
POST`/api/channels`	Follows a channel. Body: `{"input": "@handle \| URL \| UC... ID"}`. Idempotent.
GET`/api/channels/{id}/candidates`	Candidate videos from the channel, with those already archived flagged. Parameters: `sort=recent\|oldest\|popular`, `limit` (max 100), `exclude_shorts=0\|1`.
GET`/api/channels/{id}/transcripts`	All archived transcripts for the channel (warning: can be large).

Account

Endpoint	Description
GET`/api/credits`	Plan, credit balance, channel limits, and account capabilities.
GET`/api/credits/history`	Credit transaction history (last 200 entries).

Connect to Claude / Cursor (MCP server)

The MCP server exposes your library as tools: fetch a transcript, list your videos and channels, pull the transcripts of an entire channel... Streamable HTTP transport, stateless:

URL     : https://youtube.tagbuilder.dev/mcp
Header  : X-Api-Key: ytr_your_key

Claude Code

claude mcp add --transport http youtube-restitution \
  https://youtube.tagbuilder.dev/mcp \
  --header "X-Api-Key: ytr_your_key"

Cursor

In ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "youtube-restitution": {
      "url": "https://youtube.tagbuilder.dev/mcp",
      "headers": {
        "X-Api-Key": "ytr_your_key"
      }
    }
  }
}

Available tools

get_transcript: fetches and archives a video's transcript (idempotent).
list_videos / get_video: browse your library (transcript, breakdown, action plan).
follow_channel / list_channels: manage followed channels.
list_channel_videos: a channel's videos, sorted (recent, oldest, popular).
pull_channel_transcripts: archives the transcripts of N videos from a channel (deduplicated).
get_channel_transcripts: all archived transcripts for a channel.

Every transcript fetched through the API or the MCP server is archived in your library: you will find it in the app, ready for a breakdown or an action plan.