BrokenTube API Documentation

Overview

Welcome to the BrokenTube API. Our API allows developers and agencies to integrate BrokenTube's powerful link-checking and video analysis features directly into their own applications and workflows.

Authentication

To authenticate your requests, you must include your unique API Key in the header of every request:

X-API-KEY: YOUR_API_KEY

Endpoints

List Scans

Returns the most recent scans for the authenticated user.

GET /api/v1/scans

curl -H "X-API-KEY: YOUR_API_KEY" https://brokentube.com/api/v1/scans

Response

{
  "scans": [
    { "id": 123, "channel_name": "My Channel", "date": "2025-10-25T16:22:03Z", "status": "completed" }
  ]
}

Scan Detail

Returns detailed link results for a specific scan.

GET /api/v1/scan/<scan_id>

curl -H "X-API-KEY: YOUR_API_KEY" https://brokentube.com/api/v1/scan/123

Response

{
  "scan": {
    "id": 123,
    "channel_id": "UCxxxxx",
    "channel_name": "My Channel",
    "timestamp": "2025-10-25T16:22:03Z",
    "status": "completed",
    "links_total": 10
  },
  "links": [
    { "id": 1, "video_title": "Episode 1", "original_url": "http://...", "final_url": "https://...", "status": "Live", "status_code": "200" }
  ],
  "broken_links": [
    { "id": 2, "video_title": "Episode 1", "original_url": "http://...", "final_url": "http://...", "status": "Not Found", "status_code": "404" }
  ]
}

Check Links (Single Video)

Public endpoint to check links found in a single YouTube video’s description.

GET /api/free-tools/check-links?url=<youtube_url>

curl "https://brokentube.com/api/free-tools/check-links?url=https://www.youtube.com/watch?v=IvwJU7AMQh4"

Response

{
  "total": 3,
  "links": [
    { "url": "http://...", "final_url": "https://...", "status_code": 200, "status": "HEALTHY" },
    { "url": "http://...", "final_url": "http://...", "status_code": 404, "status": "BROKEN" }
  ]
}

Rate Limits & Quotas

To ensure system stability and fair usage for all users, we enforce the following rate limits:

• Basic Limit: By default, all API keys are capped at 1,000 requests.

This limit is sufficient for most individual developers and small-scale testing.

Enterprise & Custom Limits

We understand that agencies and large companies may require higher throughput for their operations.

Need a higher limit?

If you are a company or enterprise user with specific needs, we are happy to increase your quota. To request a limit increase:

1. Prepare a brief explanation of your use case and estimated volume.
2. Provide proof of your company/agency status.
3. Contact our developer support team.

Contact Us

Please send your request to [email protected] or open a ticket via our Support portal. Our team will review your application and adjust your limits accordingly.

Getting Started

1. Login to BrokenTube and navigate to Settings → API & Developers.
2. Generate an API Key if you do not have one.
3. Copy your key and keep it secure. Do not commit it to public repos.

Python Quickstart

Install the required library:

pip install requests

Use the following script to authenticate and fetch your scans:

import os
import requests

BASE_URL = "https://brokentube.com"
API_KEY = os.getenv("BROKENTUBE_API_KEY") or "YOUR_API_KEY"
HEADERS = {"X-API-KEY": API_KEY}

def list_scans():
    r = requests.get(f"{BASE_URL}/api/v1/scans", headers=HEADERS, timeout=20)
    r.raise_for_status()
    data = r.json()
    print("Scans:", data.get("scans", []))
    return data.get("scans", [])

def scan_detail(scan_id):
    r = requests.get(f"{BASE_URL}/api/v1/scan/{scan_id}", headers=HEADERS, timeout=20)
    r.raise_for_status()
    data = r.json()
    print("Scan Detail:", data)
    return data

def check_video_links(youtube_url):
    r = requests.get(f"{BASE_URL}/api/free-tools/check-links", params={"url": youtube_url}, timeout=30)
    r.raise_for_status()
    data = r.json()
    print("Link Check:", data)
    return data

if __name__ == "__main__":
    scans = list_scans()
    if scans:
        first_id = scans[0]["id"]
        scan_detail(first_id)
    # Public endpoint example (no API key needed)
    check_video_links("https://www.youtube.com/watch?v=IvwJU7AMQh4")

Best Practices

• Store your API key in environment variables (e.g., BROKENTUBE_API_KEY).
• Respect rate limits and implement retries/backoff for transient errors.
• Cache non-sensitive responses to reduce unnecessary requests.