API Documentation

Pull API

Fetch all transcripts detected for your subscriptions within a time window. Good for batch processing, scheduled jobs, or polling-based integrations.

curl https://vidproxy.pro/api/videos?since=24h&tag=my-channel \
  -H "Authorization: Bearer tr_live_xxxxxxxxxxxx"

{
  "videos": [
    {
      "id": 1234,
      "subscription_id": 42,
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_name": "HomeBrewers",
      "tag": "my-channel",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "How to Brew a West Coast IPA",
      "published_at": "2026-04-30T10:00:00.000Z",
      "transcript_available": true,
      "transcript_text": "Welcome to today's brew session...",
      "transcript_source": "proxy",
      "detected_at": "2026-04-30T10:05:12.000Z",
      "ai_summary": null,
      "ai_key_takeaways": null,
      "ai_topics": null
    }
  ],
  "query": {
    "tag": "my-channel",
    "since": "24h",
    "cutoff": "2026-04-29T10:05:12.000Z"
  }
}

Response Fields

MCP — Claude & Cursor Integration

VidProxy ships a Model Context Protocol server at https://vidproxy.pro/mcp. Add it to Claude Desktop, Cursor, VS Code, or any MCP-compatible client and your AI assistant can read your channel data, pull transcripts, check what's left on your plan, and manage which channels you monitor — no copy-pasting, no API calls to write.

Setup

Add the following to your MCP client config. For Claude Desktop that's ~/.config/claude/claude_desktop_config.json; for Cursor it's in Settings → MCP.

{
  "mcpServers": {
    "vidproxy": {
      "url": "https://vidproxy.pro/mcp",
      "headers": {
        "Authorization": "Bearer tr_live_xxxxxxxxxxxx"
      }
    }
  }
}

Your API key is in Dashboard → Settings. The MCP server uses the same key as the REST API.

Available Tools

Three of these tools write to your account — they add, pause and delete subscriptions using the same plan limits as the dashboard. Your API key is what authorises them, so treat it like a password: anyone holding it can change what you monitor. Rotate it any time in Dashboard → Settings. Webhook URLs are deliberately not settable over MCP — configure those in the dashboard.

remove_channel is disabled by default. Until you enable destructive tools for a key in Dashboard → Settings, the tool is not advertised to your assistant at all and is refused if called — every other tool works normally. Rotating a key switches it back off.

Why it works this way: the confirm: true flag is a speed bump for a well-behaved assistant, not a security boundary, because the model decides whether to set it. Transcripts are written by the channel owner, not by you, so a video whose captions contain instructions aimed at your assistant is a real possibility once that assistant can also delete things. The dashboard toggle is the part of the gate that no text your assistant reads can flip. Deletion is irreversible and we keep no per-account backup of transcripts.

Example prompts

• "Summarize everything my channels posted in the last 24 hours."
• "Search my channels for any video mentioning 'interest rates' this week."
• "Fetch the transcript for youtube.com/watch?v=abc123 and pull out the key points."
• "Which of my channels posted the most content last month?"
• "How many transcript credits do I have left this month?"
• "Start monitoring @Bloomberg and tag it finance."
• "Pause the channels I haven't gotten a video from in 60 days."

Keyword Alerts

Keyword Alerts let you save keywords and receive an email whenever any new video across all your subscriptions mentions them — matched against the video title and transcript. This is separate from per-subscription keyword filters, which control webhook delivery.

Managing alerts

Alerts are managed from the Keyword Alerts tab in your dashboard. Add a keyword, and VidProxy will email you each time a new video matches it. Up to 50 keywords per account.

Match behavior

• Case-insensitive, whole-word match — gpt matches "GPT-4" and "GPT is…" but not "ChatGPT", and fed matches "the Fed's decision" but not "federal". Phrases work (federal reserve). There is no stemming: tariff does not match "tariffs", so add both.
• Matches run against both the video title and the full transcript text.
• If a transcript is not yet available, the title is checked immediately; the transcript is checked once it becomes available.
• If multiple keywords match the same video, you receive one email listing all matched keywords.

Per-subscription keyword filter

Subscriptions also support a per-subscription Keyword Filter (set in the subscription edit modal, comma-separated, up to 25 keywords). This controls webhook delivery only — the webhook fires only when the video title or full transcript matches one of the keywords, using the same whole-word rules as above, and the payload says which ones (matched_keywords). It does not send emails and is independent of Keyword Alerts.

• A video that does not match is stored (readable through the Pull API) but not delivered; the Delivery Log records it as filtered · no keyword match.
• With a filter set, a video is held until its transcript is available, even if Wait for transcript is off — the filter has nothing to match against otherwise. If no transcript arrives within 24 hours it is skipped, never delivered unchecked, and logged as skipped · no transcript to match.
• Available on every plan, including Free. If a plan ever stops including filters, a filter left on it pauses that subscription's webhook (paused · filter not in your plan) until you clear it; clearing always works.

API

Rate Limits

The Pull API is rate-limited per API key against two windows checked together: a burst limit (sliding 60 seconds) and a sustained limit (sliding 24 hours). A request has to fit under both. Response headers tell you your current usage:

When you exceed either limit you receive a 429 Too Many Requests with a Retry-After header and a limit_type field (burst or daily) in the JSON body naming which one you hit. Back off and retry after that delay.

FAQ