BestDebrid API

Unrestrict premium links from hundreds of file hosters, expand folders and playlists, manage torrents up to 90 GiB, and integrate BestDebrid into your application. This reference documents every endpoint currently served on build 1.07.

Base URLhttps://bestdebrid.com/api/v1
Build1.07
FormatJSON
AuthAPI Key
Daily quota70 links / 24h

Introduction

The BestDebrid API is a RESTful interface returning JSON over HTTPS. Most endpoints accept both GET and POST and can receive parameters via query string or request body.

Base URL

https://bestdebrid.com/api/v1

Response envelope

Every endpoint returns a JSON object with an error integer (0 means success) and a message — either a human-readable string on failure, or a payload (string, array, object) on success. Richer endpoints (unrestrict, torrent details, hosters) add their own top-level fields alongside error.

{
  "error": 0,
  "message": "OK"
  // additional fields depending on the endpoint

}

Authentication

Every endpoint except / and /time requires your API key. Pass it one of two ways:

Option 1 — HTTP header (recommended)

Authorization: YOUR_API_KEY

Option 2 — Query string

?auth=YOUR_API_KEY
Where to find your key: sign in to your BestDebrid account — your API key is in the API section of the dashboard. Rotate it any time with /newkey.
Keep your key secret. Never expose it in client-side code, public repositories, or browser extensions shipped to end users. If it leaks, rotate it immediately.

Error handling

The error field indicates the outcome. A non-zero value is accompanied by a descriptive message. Error codes are reused across endpoints, but the meaning is always carried by the message.

0Success — the request completed.
1Missing or invalid parameter (empty link, bad API key, missing password).
2Invalid URL format — link must start with http:// or https://.
3Unsupported link, invalid magnet, or user not logged in.
4Free users cannot unrestrict this hoster (premium-only host).
5Too many active torrents (max 5 at a time) or torrent server error.
6Free daily limit reached · or duplicate torrent · or host under maintenance.
7File size exceeds the free-user limit, or link-generation error.
8Torrent size could not be determined, or torrent exceeds the 90 GiB limit.
9Hoster pre-flight quota reached (daily links on this host).
10Generation failed — the hoster returned an error.
19Hoster limit reached after the link was already generated.
21Premium plan required for API access.
22API access is banned on this account.
55Service under maintenance, or invalid parameter type (e.g. non-numeric isFile).
56Invalid IP address, waiting time not elapsed, or free-user daily quota.
121Daily download quota reached (70 unique links / 24h).
122Too many unrestricts in progress — retry in ~1 min.
632VPN/proxy detected (forbidden for free users).
Daily quota: each account is limited to 70 unique files every 24 hours across web + API (error 121). In-progress unrestricts count against the quota too (error 122).

Root — list endpoints

Returns a JSON array of human-readable strings describing every endpoint exposed by the current build. Useful for sanity checks.

GET https://bestdebrid.com/api/v1/

No authentication required.

Example response

[
  "time ( function : time of bestdebrid.com )",
  "newkey ( function : renew api key, params [ auth=apikey, pass=password of account ] )",
  "user ( function : user infos, params [ auth=apikey ] )",
  "...",
  "*******************************************************",
  "** api build [1.07]  **",
  "*******************************************************"
]
curl https://bestdebrid.com/api/v1/
<?php
$res  = file_get_contents('https://bestdebrid.com/api/v1/');
$data = json_decode($res, true);
print_r($data);
const res  = await fetch('https://bestdebrid.com/api/v1/');
const data = await res.json();
console.log(data);

Server time

Returns the current server time. Handy to sync clients or detect significant clock drift.

GET https://bestdebrid.com/api/v1/time

Example response

{
  "error": 0,
  "message": "2025-04-19 14: 22: 03"
}
curl https://bestdebrid.com/api/v1/time
<?php
$res = file_get_contents('https://bestdebrid.com/api/v1/time');
echo json_decode($res, true)['message'];
const r = await fetch('https://bestdebrid.com/api/v1/time');
console.log((await r.json()).message);

User info

Returns the profile of the authenticated user. Use this to check premium status, expiry, and whether this account bypasses API limits.

GET https://bestdebrid.com/api/v1/user

Parameters

ParameterTypeDescription
authrequiredstringYour API key — as Authorization header or ?auth= query param.

Response schema

ParameterTypeDescription
erroroptionalinteger0 on success, 1 if the key is invalid.
usernameoptionalstringAccount username.
emailoptionalstringAccount email.
creditoptionalintegerRemaining credits on the account.
IDoptionalintegerInternal user ID.
premiumoptionalbooleantrue if the account has an active premium plan (expire in the future).
expireoptionalstring|nullPremium expiry date in Y-m-d H:i:s, or null if not premium.
bypass_api_limitoptionalbooleantrue for accounts allowed to bypass per-host unrestrict limits.

Example response

{
  "error": 0,
  "username": "john_doe",
  "email": "john@example.com",
  "credit": 0,
  "ID": 12345,
  "premium": true,
  "expire": "2026-09-14 10: 20: 00",
  "bypass_api_limit": false
}
⚡ Try it out
curl -H 'Authorization: YOUR_API_KEY' \
  https://bestdebrid.com/api/v1/user
<?php
$ctx = stream_context_create(['http' => [
    'header' => "Authorization: YOUR_API_KEY\r\n"
]]);
$user = json_decode(file_get_contents('https://bestdebrid.com/api/v1/user', false, $ctx), true);
const res  = await fetch('https://bestdebrid.com/api/v1/user', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});
const user = await res.json();

Rotate API key

Generates a fresh API key. The old key is invalidated immediately. Returns the literal string true on success.

GET https://bestdebrid.com/api/v1/newkey

Parameters

ParameterTypeDescription
authrequiredstringYour current API key (or Authorization header).
passrequiredstringYour account password (or Password-X header). Used to confirm the rotation.
Headers alternative: the key is also accepted as Authorization, and the password as Password-X. When both headers and query params are present, headers win.

Example responses

On success the endpoint outputs the literal string true (not a JSON object). On failure it returns the standard error envelope:

// Success (plain text)

true

// Failure

{
  "error": 0,
  "message": "Invalid credentials"
}
curl 'https://bestdebrid.com/api/v1/newkey?auth=YOUR_API_KEY&pass=YOUR_PASSWORD'
<?php
$url = 'https://bestdebrid.com/api/v1/newkey?auth=YOUR_API_KEY&pass=YOUR_PASSWORD';
$res = file_get_contents($url);

if (trim($res) === 'true') {
    // success — fetch the new key via /user or from your account page
}
const res = await fetch('https://bestdebrid.com/api/v1/newkey?auth=YOUR_API_KEY&pass=YOUR_PASSWORD');
const ok = (await res.text()).trim() === 'true';

Downloads history

Returns the user's most recent unrestricted links as an associative object keyed starting at "1" (not a flat JSON array).

GET https://bestdebrid.com/api/v1/downloadsHistory

Parameters

ParameterTypeDescription
authrequiredstringYour API key.
numoptionalintegerNumber of entries to return. Default 10, capped at 300.

Response schema (each entry)

ParameterTypeDescription
nameoptionalstringFilename of the downloaded file.
linkoptionalstringGenerated unrestricted download link.
originaloptionalstringOriginal hoster URL you submitted.
ipoptionalstringClient IP that triggered the download.
dateoptionalstringTimestamp Y-m-d H:i:s.

Example response

{
  "1": {
    "name": "Movie.mkv",
    "link": "https://debrid2.bestdebrid.com/dl/TY/abc.../Movie.mkv",

    "original": "https://rapidgator.net/file/abc123",

    "ip": "1.2.3.4",
    "date": "2025-04-18 22: 13: 07"
  },
  "2": {
    "name": "Archive.zip",
    "link": "https://debrid1.bestdebrid.com/dl/TY/def.../Archive.zip",

    "original": "https://k2s.cc/file/def456",

    "ip": "1.2.3.4",
    "date": "2025-04-18 21: 02: 55"
  }
}
⚡ Try it out
curl -H 'Authorization: YOUR_API_KEY' \
  'https://bestdebrid.com/api/v1/downloadsHistory?num=20'
<?php
$ctx = stream_context_create(['http' => ['header' => "Authorization: YOUR_API_KEY\r\n"]]);
$history = json_decode(file_get_contents('https://bestdebrid.com/api/v1/downloadsHistory?num=20', false, $ctx), true);

foreach ($history as $entry) {
    echo $entry['name'] . "\n";
}
const res  = await fetch('https://bestdebrid.com/api/v1/downloadsHistory?num=20', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});
const history = await res.json();
Object.values(history).forEach(e => console.log(e.name));

Supported hosters

Returns the full list of premium hosters on the platform, each with status, icon paths, and an explicit hostfolder flag that tells you whether the hoster can be expanded via /hostfolder.

GET https://bestdebrid.com/api/v1/hosts

Parameters

ParameterTypeDescription
authrequiredstringYour API key.

Response schema (per hoster)

ParameterTypeDescription
nameoptionalstringHoster identifier (e.g. rapidgator, mega).
statusoptionalstringup or down.
pictureoptionalstringRelative path to the standard icon (img/hosters/name.png).
picture_100_100optionalstringRelative path to the 100×100 icon.
lastcheckoptionalstringTimestamp of the last availability check.
downsincedateoptionalstringTimestamp since the hoster is down (empty string if up).
hostfolderoptionalbooleantrue if the hoster supports folder/playlist expansion via /hostfolder. Currently true for gofile, youtube, mega, terabox.
domainsoptionalstring[]Array of domain aliases handled as this hoster (e.g. rapidgator.net, rg.to).

Example response (truncated)

[
  {
    "name": "rapidgator",
    "status": "up",
    "picture": "img/hosters/rapidgator.png",
    "picture_100_100": "img/hosters/100_100/rapidgator.png",
    "lastcheck": "2025-04-19 14: 00: 12",
    "downsincedate": "",
    "hostfolder": false,
    "domains": ["rapidgator.net", "rg.to"]
  },
  {
    "name": "mega",
    "status": "up",
    "picture": "img/hosters/mega.png",
    "picture_100_100": "img/hosters/100_100/mega.png",
    "lastcheck": "2025-04-19 14: 00: 14",
    "downsincedate": "",
    "hostfolder": true,
    "domains": ["mega.io", "mega.nz", "mega.co.nz"]
  }
]
⚡ Try it out
curl -H 'Authorization: YOUR_API_KEY' https://bestdebrid.com/api/v1/hosts
<?php
$ctx = stream_context_create(['http' => ['header' => "Authorization: YOUR_API_KEY\r\n"]]);
$hosts = json_decode(file_get_contents('https://bestdebrid.com/api/v1/hosts', false, $ctx), true);

// Build a quick lookup: domain -> hoster entry
$byDomain = [];
foreach ($hosts as $h) {
    foreach ($h['domains'] as $d) $byDomain[$d] = $h;
}
const hosts = await (await fetch('https://bestdebrid.com/api/v1/hosts', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
})).json();

const needsFolderExpand = hosts
  .filter(h => h.hostfolder && h.status === 'up')
  .map(h => h.name);

Hoster counts

Aggregate counts of premium hosters currently up vs. down. Useful for status dashboards.

GET https://bestdebrid.com/api/v1/hostscount

Parameters

ParameterTypeDescription
authrequiredstringYour API key.

Response schema

ParameterTypeDescription
totalhostsoptionalintegerTotal number of premium hosters.
hostsupoptionalintegerHosters currently marked up.
hostsdownoptionalintegerHosters currently marked down.

Example response

{
  "totalhosts": 87,
  "hostsup": 81,
  "hostsdown": 6
}
⚡ Try it out

Hoster limits

Returns the per-hoster daily limits (number of downloads and total bandwidth) currently advertised to end users.

GET https://bestdebrid.com/api/v1/hostslimits

Parameters

ParameterTypeDescription
authrequiredstringYour API key.

Response schema (per hoster)

ParameterTypeDescription
nameoptionalstringHoster identifier.
linksperdayoptionalintegerMax daily unrestricts visible to users (raw DB value ÷ 2).
bandwidthoptionalstringDaily bandwidth cap formatted with units (e.g. "150 GB"). "∞" when unlimited.
pictureoptionalstringRelative path to the standard icon.
picture_100_100optionalstringRelative path to the 100×100 icon.

Example response (truncated)

[
  {
    "name": "rapidgator",
    "linksperday": 25,
    "bandwidth": "150 GB",
    "picture": "img/hosters/rapidgator.png",
    "picture_100_100": "img/hosters/100_100/rapidgator.png"
  },
  {
    "name": "k2s",
    "linksperday": 50,
    "bandwidth": "∞",
    "picture": "img/hosters/k2s.png",
    "picture_100_100": "img/hosters/100_100/k2s.png"
  }
]
⚡ Try it out

Expand a folder / playlist

Resolves a folder, share or playlist into a flat list of individual file URLs you can then pass to /generateLink. Currently supports Gofile, TeraBox (and every alias: terabox.app, teraboxapp.com, mirrobox.com, 4funbox.com, 1024terabox.com, nephobox.com), YouTube playlists, and Mega folders.

POST https://bestdebrid.com/api/v1/hostfolder

Parameters

ParameterTypeDescription
authrequiredstringYour API key.
linkrequiredstringThe folder / playlist URL.
listoptionalstringYouTube playlist ID — only needed if the link is a YouTube URL missing list=.
diroptionalstringTeraBox sub-path inside the share.
pathoptionalstringAlias for dir.
fsidoptionalstringTeraBox file ID — filters a single file from the share.
fileNameoptionalstringTeraBox filename filter (use with fsid).

Response schema

ParameterTypeDescription
erroroptionalinteger0 on success, 1 on failure.
messageoptionalstring[] | stringArray of resolved URLs on success; human-readable error message on failure.

Example responses

// Gofile

{
  "error": 0,
  "message": [
    "https://gofile.io/download/abc123?server=store1",

    "https://gofile.io/download/def456?server=store2"

  ]
}

// Non-supported hoster — link echoed back

{
  "error": 0,
  "message": ["https://rapidgator.net/file/abc123"]

}

// Folder with no direct files (TeraBox)

{
  "error": 1,
  "message": "This link contains folders only. We can only unrestrict folders that contain actual files. Please open your link and navigate through the folders until you reach a folder that contains files."
}
Safe to pipe every URL through /hostfolder. If the URL isn\'t a known folder type, the endpoint simply echoes it back wrapped in the message array — your client code can always expand → unrestrict without branching.
⚡ Try it out
curl -X POST https://bestdebrid.com/api/v1/hostfolder \
  -H 'Authorization: YOUR_API_KEY' \
  --data-urlencode 'link=https://gofile.io/d/XXXXX'
<?php
$ch = curl_init('https://bestdebrid.com/api/v1/hostfolder');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: YOUR_API_KEY'],
    CURLOPT_POSTFIELDS     => http_build_query(['link' => $folderLink]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$files = ($response['error'] === 0) ? $response['message'] : [];
const res = await fetch('https://bestdebrid.com/api/v1/hostfolder', {
  method : 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY' },
  body   : new URLSearchParams({ link: folderLink })
});
const { error, message } = await res.json();
const files = error === 0 ? message : [];

Add torrent / magnet

Queues a magnet link or an uploaded .torrent file for download. Downloaded files are then served as regular HTTPS links via /gettorrentFile.

POST https://bestdebrid.com/api/v1/torrentFile

Parameters

ParameterTypeDescription
authrequiredstringYour API key.
magnetrequiredstringMagnet URI, or base64-encoded .torrent file bytes when isFile=1.
isFileoptionalinteger1 if magnet is a base64 torrent file, 0 for a magnet URI (default 0). Must be numeric — non-numeric values return error 55.
nocheckoptionalbooleanSkip the duplicate check (otherwise adding the same torrent twice returns error 6). Default false.
ipoptionalstringIP address allowed to later download the resulting files. Must be a valid IPv4/IPv6.

Response schema

ParameterTypeDescription
erroroptionalinteger0 on success.
messageoptionalstring"OK" on success.
torrent_idoptionalstringTorrent infohash — use it with /gettorrentFile and /deltorrentFile.
torrent_linkoptionalstringHTML-escaped torrent name.

Example response

{
  "error": 0,
  "message": "OK",
  "torrent_id": "dc6521c4fec8641eaa5901164c8e57e16a790e05",
  "torrent_link": "Ubuntu.22.04.LTS.iso"
}
Limits:
  • Premium plan required.
  • Max 5 active torrents per account (error 5).
  • Max torrent size: 90 GiB (error 8).
  • Duplicate magnet/torrent within 4 days: error 6 unless nocheck=true.
  • If total size can\'t be read from the swarm within ~30 s the torrent is removed and error 8 is returned.
# magnet URI
curl -X POST https://bestdebrid.com/api/v1/torrentFile \
  -H 'Authorization: YOUR_API_KEY' \
  --data-urlencode 'magnet=magnet:?xt=urn:btih:dc6521c4fec8641eaa5901164c8e57e16a790e05' \
  --data 'isFile=0'
<?php
// Adding a magnet
$ch = curl_init('https://bestdebrid.com/api/v1/torrentFile');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: YOUR_API_KEY'],
    CURLOPT_POSTFIELDS     => http_build_query([
        'magnet' => 'magnet:?xt=urn:btih:...',
        'isFile' => 0,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Adding a .torrent file
$torrentBytes = file_get_contents('/path/to/file.torrent');
$encoded      = base64_encode($torrentBytes);
// ... POST with magnet=$encoded & isFile=1
// magnet
await fetch('https://bestdebrid.com/api/v1/torrentFile', {
  method : 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY' },
  body   : new URLSearchParams({
    magnet: 'magnet:?xt=urn:btih:...',
    isFile: '0'
  })
});

// .torrent file
const buf = await fetch('/my.torrent').then(r => r.arrayBuffer());
const b64 = btoa(String.fromCharCode(...new Uint8Array(buf)));
await fetch('https://bestdebrid.com/api/v1/torrentFile', {
  method : 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY' },
  body   : new URLSearchParams({ magnet: b64, isFile: '1' })
});

List active torrents

Returns up to the 5 most recent active torrents of the account (completed, in-progress, or queued — not deleted).

GET https://bestdebrid.com/api/v1/gettorrentList

Parameters

ParameterTypeDescription
authrequiredstringYour API key.

Response schema (per entry)

ParameterTypeDescription
idoptionalstringTorrent infohash (use as torrentid in other endpoints).
nameoptionalstringTorrent display name.
ipoptionalstringIP that was locked to this torrent.
dateoptionalstringTimestamp when the torrent was added.

Example response

[
  {
    "id": "dc6521c4fec8641eaa5901164c8e57e16a790e05",
    "name": "Ubuntu.22.04.LTS.iso",
    "ip": "1.2.3.4",
    "date": "2025-04-19 10: 12: 34"
  }
]
⚡ Try it out
curl -H 'Authorization: YOUR_API_KEY' https://bestdebrid.com/api/v1/gettorrentList
<?php
$ctx = stream_context_create(['http' => ['header' => "Authorization: YOUR_API_KEY\r\n"]]);
$list = json_decode(file_get_contents('https://bestdebrid.com/api/v1/gettorrentList', false, $ctx), true);
const list = await (await fetch('https://bestdebrid.com/api/v1/gettorrentList', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
})).json();

Get torrent details

Returns full details of a single torrent: progress, ratio, size, speed, and — once finished — the list of downloadable file URLs plus a ZIP archive URL.

GET https://bestdebrid.com/api/v1/gettorrentFile

Parameters

ParameterTypeDescription
authrequiredstringYour API key.
torrentidrequiredstringTorrent infohash returned by /torrentFile or /gettorrentList.

Response schema

ParameterTypeDescription
erroroptionalinteger0 on success.
idoptionalstringTorrent infohash.
messageoptionalstring"OK".
filenameoptionalstringTorrent display name.
img-progressoptionalstringRelative path to a status icon (img/torrents/ok.gif, deb-loading.gif, wait.png, error.gif).
progressoptionalfloatPercent done (01).
ratiooptionalfloat | stringUpload ratio; empty string when unknown.
seedersoptionalintegerNumber of connected peers.
sizeoptionalintegerTotal size in bytes.
sizeStringoptionalstringHuman-readable size (e.g. "3.2 GB").
speedoptionalstringCurrent download speed (e.g. "4.52 MB/s").
serverIDoptionalintegerInternal ID of the seedbox storing the torrent.
linksoptionalobject | stringOnce finished, an object with zip (URL to full ZIP) and files (array of per-file URLs). While still downloading, the literal string "Waiting...".

Example response

{
  "error": 0,
  "id": "dc6521c4fec8641eaa5901164c8e57e16a790e05",
  "message": "OK",
  "filename": "Ubuntu.22.04.LTS.iso",
  "img-progress": "img/torrents/ok.gif",
  "progress": 1,
  "ratio": 1.23,
  "seeders": 12,
  "size": 3489660928,
  "sizeString": "3.25 GB",
  "speed": "0.00 MB/s",
  "serverID": 4,
  "links": {
    "zip": "https://seedbox.bestdebrid.com/index.php?zip=dc6521...&filename=Ubuntu.22.04.LTS.iso",

    "files": [
      "https://seedbox.bestdebrid.com/index.php?filename=dc6521...&id=Ubuntu.22.04.LTS.iso"

    ]
  }
}
ZIP endpoint: the links.zip URL lets you download the entire torrent content as a single compressed archive — convenient for multi-file releases.
⚡ Try it out
curl -H 'Authorization: YOUR_API_KEY' \
  'https://bestdebrid.com/api/v1/gettorrentFile?torrentid=dc6521c4...'
<?php
$ctx = stream_context_create(['http' => ['header' => "Authorization: YOUR_API_KEY\r\n"]]);
$t = json_decode(file_get_contents('https://bestdebrid.com/api/v1/gettorrentFile?torrentid=' . $hash, false, $ctx), true);

if ($t['error'] === 0 && is_array($t['links'])) {
    $zip   = $t['links']['zip'];
    $files = $t['links']['files'];
}
const t = await (await fetch('https://bestdebrid.com/api/v1/gettorrentFile?torrentid=' + hash, {
  headers: { 'Authorization': 'YOUR_API_KEY' }
})).json();

if (t.error === 0 && typeof t.links === 'object') {
  const zipUrl = t.links.zip;
  const files  = t.links.files;
}

Delete a torrent

Removes a torrent from the account. Underlying files are wiped from the seedbox only once no other user has added the same torrent in the last 4 days and its upload ratio ≥ 1.

DELETE https://bestdebrid.com/api/v1/deltorrentFile

Parameters

ParameterTypeDescription
authrequiredstringYour API key.
torrentidrequiredstringTorrent infohash to delete.

Example response

{
  "error": 0,
  "message": "Torrent deleted"
}
Irreversible. The torrent entry and any generated download links will no longer be accessible from your account.
curl -H 'Authorization: YOUR_API_KEY' \
  'https://bestdebrid.com/api/v1/deltorrentFile?torrentid=dc6521c4...'
<?php
$ctx = stream_context_create(['http' => ['header' => "Authorization: YOUR_API_KEY\r\n"]]);
$r = json_decode(file_get_contents('https://bestdebrid.com/api/v1/deltorrentFile?torrentid=' . $hash, false, $ctx), true);
await fetch('https://bestdebrid.com/api/v1/deltorrentFile?torrentid=' + hash, {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});