API Reference � The Black Hole Bay

Getting Started

Everything you need to start using the API.

Base URL

All API requests should be made to:

text

https://theblackholebay.lol

Note: All endpoints are prefixed with /api. Example: https://theblackholebay.lol/api/search?q=dune

Authentication

No authentication is required for any public endpoint.

Header	Required	Description
Authorization	No	Not required
API-Key	No	Not required

Note: All third-party API keys (TMDB, RAWG) are kept server-side and are never exposed in client responses.

Rate Limiting

The API uses IP-based rate limiting.

Setting	Value
Requests	120 / minute / IP
Enforcement	Automatic
Exceeded	`429 Too Many Requests`
IP cleanup	Every 60 seconds

Applications should use exponential backoff when receiving 429 responses:

javascript

async function fetchWithRetry(url, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;
    const delay = 1000 * 2 ** attempt;
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded");
}

Response Format

All responses are JSON with the following headers:

Header	Value
Content-Type	application/json; charset=utf-8
Cache-Control	no-store

Clients should implement their own short-lived caching for repeated requests.

Torrent API

Search torrents, get metadata, list files, and track downloads.

GET/api/search

Searches The Pirate Bay, 1337x, and local index simultaneously. Results are merged and deduplicated.

Parameter	Required	Default	Description
q	No	""	Search query. Empty = browse latest uploads
category	No	0	Category code (see below)
page	No	0	Page number

Category codes: 0=All, 100=Audio, 200=Video, 300=Apps, 400=Games, 500=Adult, 600=Other

bash

curl "https://theblackholebay.lol/api/search?q=breaking+bad&category=200"

json

{
  "query": "breaking bad",
  "source": "remote_api+local+1337x",
  "results": [{
    "id": "4034523",
    "name": "Breaking.Bad.S01E01.1080p.BluRay.x265",
    "info_hash": "abc123def456...",
    "magnet": "magnet:?xt=urn:btih:abc123def456...",
    "seeders": 245,
    "leechers": 12,
    "size": 1073741824,
    "sizeLabel": "1.00 GiB",
    "category": 200,
    "added": 1700000000,
    "username": "uploader123",
    "status": "trusted",
    "source": "TPB"
  }]
}

Field	Type	Description
id	string	Unique torrent ID
name	string	Torrent title
info_hash	string	BitTorrent info hash
magnet	string	Full magnet URI with trackers
seeders	number	Active seeders
leechers	number	Active leechers
size	number	Size in bytes
sizeLabel	string	Human-readable size
added	number	Unix timestamp
status	string	Uploader status (trusted/vip)
source	string	Origin: TPB, 1337x, or Local

Fallback: If the TPB API is down, source becomes "local_fallback+1337x" and results come from the local index + 1337x.

GET/api/torrent/{id}

Returns full metadata for a single torrent.

bash

curl "https://theblackholebay.lol/api/torrent/4034523"

json

{ "torrent": { "id":"4034523", "name":"...", "magnet":"magnet:?...", "seeders":245, "sizeLabel":"1.00 GiB" } }

GET/api/files/{id}

Returns the list of files inside a torrent.

json

{
  "files": [
    { "name": "video.mkv", "size": 1073741824, "sizeLabel": "1.00 GiB" },
    { "name": "subs.srt", "size": 45200, "sizeLabel": "44.14 KiB" }
  ]
}

GET/api/track/download

Increments the download counter. Call this when a user clicks a magnet link.

json

{ "ok": true }

Movies & TV

Movie and TV metadata powered by TMDB.

GET/api/upcoming?page=1

Movies currently in theaters. Posters cached locally.

Parameter	Default	Description
page	1	Page number (20 per page)

Note: poster_path returns a local path: /upcoming/images/{id}.jpg � use directly as https://theblackholebay.lol/upcoming/images/{id}.jpg. Movies older than 90 days are filtered out.

GET/api/tv_airing?page=1

Currently popular TV shows, filtered to the last 5 years.

Parameter	Default	Description
page	1	Page number

GET/api/movie/{id}

Full movie details including cast, runtime, genres, and IMDb link.

json

{
  "id": 872585,
  "title": "Oppenheimer",
  "runtime": 180,
  "imdb_id": "tt15398776",
  "genres": [{ "name": "Drama" }],
  "credits": {
    "cast": [{ "name": "Cillian Murphy", "character": "Oppenheimer" }]
  }
}

GET/api/tv/{id}

Full TV show details including cast, seasons, and episodes.

json

{
  "name": "Show Name",
  "number_of_seasons": 3,
  "number_of_episodes": 24,
  "episode_run_time": [55],
  "status": "Returning Series"
}

Games

Game metadata powered by RAWG.

GET/api/trending_games

Recently released games from the last 6 months, sorted by release date. Filtered to modern platforms (PC, PS4, PS5, Xbox One, Xbox Series, Switch). Up to 24 results.

json

{
  "results": [{
    "name": "Black Myth: Wukong",
    "background_image": "https://media.rawg.io/media/games/xxx.jpg",
    "released": "2024-08-20",
    "rating": "85",
    "genres": "Action, RPG",
    "platforms": "PC, PlayStation 5"
  }]
}

Field	Type	Description
name	string	Game name
background_image	string	Direct image URL � use as-is
released	string	Release date (YYYY-MM-DD)
rating	string?	Metacritic score or RAWG rating
genres	string	Comma-separated genre names
platforms	string	Comma-separated platform names

Image URLs

Source	Format
TMDB	`https://image.tmdb.org/t/p/{size}{path}` � sizes: w342, w500, w780, original
Local cache	`https://theblackholebay.lol/upcoming/images/{id}.jpg`
RAWG	Use `background_image` URL directly

Errors

Status	Meaning	Response
403	IP blocked	`Forbidden: IP banned.`
404	Not found	`{ "error": "Failed." }`
429	Rate limit exceeded	`Too Many Requests.`
500	Server error	`{ "error": "Internal Server Error" }`

Code Examples

JavaScript

javascript

const API = "https://theblackholebay.lol";

// Search torrents
const res = await fetch(`${API}/api/search?q=oppenheimer&category=200`);
const data = await res.json();

data.results.forEach(t => {
  console.log(`${t.name} | ${t.sizeLabel} | S:${t.seeders} L:${t.leechers}`);
});

// Trending movies
const movies = await fetch(`${API}/api/trending`).then(r => r.json());
movies.results.forEach(m => {
  console.log(`${m.title} (${m.vote_average}/10)`);
});

Python

python

import requests

API = "https://theblackholebay.lol"

response = requests.get(f"{API}/api/search", params={
    "q": "breaking bad", "category": 200, "page": 0
}, timeout=10)

for torrent in response.json()["results"]:
    print(f"{torrent['name']} | {torrent['sizeLabel']}")

cURL

bash

# Search
curl "https://theblackholebay.lol/api/search?q=dune&category=200"

# Trending movies
curl "https://theblackholebay.lol/api/trending"

# Trending games
curl "https://theblackholebay.lol/api/trending_games"

# Movie details
curl "https://theblackholebay.lol/api/movie/872585"

Minimal API Client

javascript

const API = "https://theblackholebay.lol";

const client = {
  search: (q, cat = 0) =>
    fetch(`${API}/api/search?q=${q}&category=${cat}`).then(r => r.json()),

  torrent: (id) =>
    fetch(`${API}/api/torrent/${id}`).then(r => r.json()),

  files: (id) =>
    fetch(`${API}/api/files/${id}`).then(r => r.json()),

  trendingMovies: () =>
    fetch(`${API}/api/trending`).then(r => r.json()),

  trendingTV: () =>
    fetch(`${API}/api/trending_tv`).then(r => r.json()),

  trendingGames: () =>
    fetch(`${API}/api/trending_games`).then(r => r.json()),

  movie: (id) =>
    fetch(`${API}/api/movie/${id}`).then(r => r.json()),

  tv: (id) =>
    fetch(`${API}/api/tv/${id}`).then(r => r.json())
};

Best Practices

Caching

API responses use Cache-Control: no-store. For frequently-requested data (like trending movies), implement your own short-lived cache (30-60 seconds) to avoid hitting rate limits.

Error Handling

javascript

switch (response.status) {
  case 200: break;           // Success
  case 403: break;           // IP blocked
  case 404: break;           // Not found
  case 429: break;           // Back off and retry
  case 500: break;           // Temporary failure
}

Security

Do not expose provider API keys in frontend applications. All keys are kept server-side. The recommended architecture is:

text

Frontend ? HTTPS ? Your App ? Server-side request ? The Black Hole Bay API