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.
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.
GEThttps://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] **",
"*******************************************************"
]
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.
GEThttps://bestdebrid.com/api/v1/newkey
Parameters
Parameter
Type
Description
authrequired
string
Your current API key (or Authorization header).
passrequired
string
Your 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:
<?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).
GEThttps://bestdebrid.com/api/v1/downloadsHistory
Parameters
Parameter
Type
Description
authrequired
string
Your API key.
numoptional
integer
Number of entries to return. Default 10, capped at 300.
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.
GEThttps://bestdebrid.com/api/v1/hosts
Parameters
Parameter
Type
Description
authrequired
string
Your API key.
Response schema (per hoster)
Parameter
Type
Description
nameoptional
string
Hoster identifier (e.g. rapidgator, mega).
statusoptional
string
up or down.
pictureoptional
string
Relative path to the standard icon (img/hosters/name.png).
picture_100_100optional
string
Relative path to the 100×100 icon.
lastcheckoptional
string
Timestamp of the last availability check.
downsincedateoptional
string
Timestamp since the hoster is down (empty string if up).
hostfolderoptional
boolean
true if the hoster supports folder/playlist expansion via /hostfolder. Currently true for gofile, youtube, mega, terabox.
domainsoptional
string[]
Array of domain aliases handled as this hoster (e.g. rapidgator.net, rg.to).
The main endpoint. Takes a hoster link (or up to 5 separated by newlines) and returns unrestricted URLs you can hand to any HTTP client or download manager.
POSThttps://bestdebrid.com/api/v1/generateLink
Works as both GET and POST. Up to 5 links per call, separated by \r\n / \n.
Parameters
Parameter
Type
Description
authrequired
string
Your API key.
linkrequired
string
The hoster URL (or multiple URLs separated by newlines).
passoptional
string
Password protecting the file on the hoster, if any.
ipoptional
string
IP allowed to download the unrestricted URL. Defaults to REMOTE_ADDR. Must be a valid IPv4/IPv6.
redirectoptional
string
If set to yes, returns a 302 to the unrestricted URL instead of JSON.
Response schema (base)
Parameter
Type
Description
erroroptional
integer
0 on success, non-zero otherwise (see error table).
messageoptional
string
"OK" on success, human-readable otherwise.
original_linkoptional
string
Original hoster URL submitted.
servIdoptional
string
Internal ID of the generation server that processed the link.
hosteroptional
string
Detected hoster name.
hoster-iconoptional
string
Relative path to the hoster icon.
filenameoptional
string
Name of the file.
linkoptional
string
The unrestricted download URL.
sizeoptional
string
Human-readable file size (e.g. "1.35 GiB").
Additional fields for streamable files
When the file extension matches the platform\'s stream whitelist (mp4, mkv, avi, ...), extra fields are added:
Parameter
Type
Description
streamoptional
string
Query-string suffix for the web stream player.
streammp4optional
string
Direct MP4 transcode URL (when the stream system is enabled).
Hostname normalization: the API automatically rewrites aliases before processing. For example rg.to → rapidgator.net, keep2share.cc → k2s.cc, fr.scribd.com → scribd.com, various mixdrop.* → mixdrop.ag, TeraBox mirrors → terabox.com, and so on.
Free-user restrictions: free accounts can only unrestrict links from hosters flagged as free where at least one free server is up. VPN/proxy usage is forbidden on free accounts (error 632). A per-file size cap may also apply.
const body = new URLSearchParams({
link: 'https://rapidgator.net/file/abc123'
});
const res = await fetch('https://bestdebrid.com/api/v1/generateLink', {
method : 'POST',
headers: { 'Authorization': 'YOUR_API_KEY' },
body
});
const data = await res.json();
if (data.error === 0) console.log(data.link);
import requests
r = requests.post('https://bestdebrid.com/api/v1/generateLink',
headers={'Authorization': 'YOUR_API_KEY'},
data={'link': 'https://rapidgator.net/file/abc123'})
data = r.json()
if data['error'] == 0:
print(data['link'])
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.
POSThttps://bestdebrid.com/api/v1/hostfolder
Parameters
Parameter
Type
Description
authrequired
string
Your API key.
linkrequired
string
The folder / playlist URL.
listoptional
string
YouTube playlist ID — only needed if the link is a YouTube URL missing list=.
diroptional
string
TeraBox sub-path inside the share.
pathoptional
string
Alias for dir.
fsidoptional
string
TeraBox file ID — filters a single file from the share.
fileNameoptional
string
TeraBox filename filter (use with fsid).
Response schema
Parameter
Type
Description
erroroptional
integer
0 on success, 1 on failure.
messageoptional
string[] | string
Array 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.
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.
GEThttps://bestdebrid.com/api/v1/gettorrentFile
Parameters
Parameter
Type
Description
authrequired
string
Your API key.
torrentidrequired
string
Torrent infohash returned by /torrentFile or /gettorrentList.
Response schema
Parameter
Type
Description
erroroptional
integer
0 on success.
idoptional
string
Torrent infohash.
messageoptional
string
"OK".
filenameoptional
string
Torrent display name.
img-progressoptional
string
Relative path to a status icon (img/torrents/ok.gif, deb-loading.gif, wait.png, error.gif).
progressoptional
float
Percent done (0–1).
ratiooptional
float | string
Upload ratio; empty string when unknown.
seedersoptional
integer
Number of connected peers.
sizeoptional
integer
Total size in bytes.
sizeStringoptional
string
Human-readable size (e.g. "3.2 GB").
speedoptional
string
Current download speed (e.g. "4.52 MB/s").
serverIDoptional
integer
Internal ID of the seedbox storing the torrent.
linksoptional
object | string
Once finished, an object with zip (URL to full ZIP) and files (array of per-file URLs). While still downloading, the literal string "Waiting...".
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.