Agent API

How it works

YouTube Collector exposes two surfaces for agents:

• The standard HTTP API at /api/*, authenticated with a per-user Bearer token. Every endpoint you can call from a browser session, an agent can call programmatically.
• An MCP server at /mcp that wraps the same API with a JSON-RPC 2.0 surface. MCP-capable agents (Claude Desktop, OpenClaw, anything built on the Model Context Protocol) discover the tools automatically.

1. Generate a token

Sign in, open Settings → Agent access, click + New token, and give it a name (e.g. OpenClaw). The full token is shown exactly once on creation — copy it immediately. If you lose it, revoke and generate a new one.

Tokens look like:

ytc_user_8x7Kj2pN4vQ9mR6wT3yL5dF1cA8bZ7eH0gJ2nP4kV6sM3rD9tY1u

Per-plan limits

2. Call the HTTP API

Set the Authorization header on any existing /api/* endpoint:

curl -H "Authorization: Bearer ytc_user_…" \
  https://www.youtubecollector.online/api/me

Common endpoints:

3. Or speak MCP

If your agent supports Model Context Protocol, point it at https://www.youtubecollector.online/mcp with the same Bearer token. Transport is Streamable HTTP (a single POST endpoint speaking JSON-RPC 2.0). Tools are auto-discovered via tools/list.

Tools exposed

Example: tools/call

curl -X POST https://www.youtubecollector.online/mcp \
  -H "Authorization: Bearer ytc_user_…" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_my_videos",
      "arguments": { "search": "levels", "per_page": 5 }
    }
  }'

Claude Desktop wiring

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-collector": {
      "url": "https://www.youtubecollector.online/mcp",
      "headers": {
        "Authorization": "Bearer ytc_user_…"
      }
    }
  }
}

Rate limits and errors

Every token has a per-minute rate limit. Exceeding it returns HTTP 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": "Rate limit exceeded for this agent token",
  "error_code": "rate_limited",
  "error_details": {
    "rate_limit_per_min": 60,
    "retry_after_seconds": 23
  }
}

Common error codes you'll see:

• rate_limited — 429, slow down and honour Retry-After.
• validation_error — 400, request body / query was malformed.
• forbidden — 403, your tier doesn't allow this action (e.g. trying to mint a token from an agent-token-authenticated session).
• not_found — 404, video / token / collection doesn't exist.
• quota_exceeded — 402, you've used up the monthly summary / repurpose quota and have no credits to overspend with. Add credits or wait for the next month.

What an agent cannot do

By design:

• Mint or revoke other agent tokens (only browser session can manage tokens).
• Operate on another user's library.
• Reach any /admin/* endpoint.
• Bypass billing, quotas, or rate limits.
• Trigger unproxied YouTube traffic — every transcript fetch routes through the same residential-proxy cascade as a browser click.

Security and revocation

• Tokens are stored bcrypt-hashed. The plaintext is shown to you exactly once on creation. We cannot recover a lost token — you generate a new one and revoke the old.
• Revoke any token from Settings → Agent access. Agents using a revoked token immediately get 401 on the next call.
• If a token leaks, revoke it. Revocation is instant.
• Tokens persist independently of your password. Treat them like API keys.

Feedback

This API surface is new. If something is missing or behaves oddly, tell us or open an issue against your own workflow. The goal is for agents to operate the app exactly as you would.