Download client API

This HTTP API lets third-party download managers (e.g. JDownloader) use your account without your website password. Authenticate with a personal API key you create in Profile → API access (after signing in).

This documentation page is public; only API calls require the key.

• Base URL: https://<your-portal-host>
• API prefix: /api/external/v1
• Format: JSON only
• Timestamps: milliseconds since Unix epoch where noted

Authentication

Send the API key on every request, using one of:

Keys are opaque strings starting with obb_. Store the key only on the client side; we keep a hash server-side. If you rotate the key in Profile, old keys stop working immediately.

---

Endpoints

1. Account / traffic

GET /api/external/v1/account

Success (200):

{
  "success": true,
  "data": {
    "accountType": "premium",
    "trafficleft": 466894644646,
    "trafficmax": 1099511627776,
    "trafficmax_daily": 64424509440,
    "timeleft": null,
    "login_check_interval": 1800000
  }
}

---

2. Supported hosts

GET /api/external/v1/hosts

Success (200):

{
  "success": true,
  "data": {
    "supportedhosts": [
      {
        "host": "rapidgator.net",
        "maxChunks": 16,
        "maxDownloads": 3,
        "resumable": true,
        "currently_working": true,
        "trafficleft": 50000000000,
        "trafficmax_daily": 200000000000
      }
    ],
    "updated_at": 1710000000000
  }
}

Same authentication as other external endpoints. GET /api/external/v1/hosts returns one row per URL hostname (e.g. separate rows for rapidgator.net and rg.to). The response does not include an explicit platform field; infer grouping from identical trafficleft / trafficmax_daily pairs if needed. Prefer GET /api/external/v1/hosts/grouped if you want one row per file-hosting service with alternate domains and a stable platform id.

---

2b. Supported hosts — grouped by service

GET /api/external/v1/hosts/grouped

Same source as /hosts, but entries sharing the same backend adapter are merged. Each item includes a canonical host (first hostname in host list for that service), a sorted domains array of all URL hostnames for that service, the internal adapter id as platform, and merged limits (maxChunks / maxDownloads are maxima across domains; resumable and currently_working require all underlying rows to match). trafficleft and trafficmax_daily are the same per-platform aggregates as in /hosts (one value per grouped row).

Success (200):

{
  "success": true,
  "data": {
    "supportedhosts": [
      {
        "platform": "RapidGator",
        "host": "rapidgator.net",
        "domains": ["rapidgator.net", "rg.to"],
        "maxChunks": 16,
        "maxDownloads": 3,
        "resumable": true,
        "currently_working": true,
        "trafficleft": 50000000000,
        "trafficmax_daily": 200000000000
      }
    ],
    "updated_at": 1710000000000
  }
}

---

3. Unrestrict / start resolve (submit URL)

POST /api/external/v1/unrestrict

Body:

{
  "url": "https://rapidgator.net/file/xxxxx/example.avi",
  "password": "optional-host-password-reserved"
}

password is accepted for forward compatibility; host-specific password handling may be extended later.

Important: Our server may still be fetching the file from the host after this call. The proxy URL is not guaranteed to be usable until the file is fully downloaded to our storage. Use **download_ready** and poll **GET /api/external/v1/link/{linkId}** until download_ready is true.

Success (200) — file still downloading on our side:

{
  "success": true,
  "data": {
    "linkId": "abc123",
    "download_ready": false,
    "remote_status": "downloading",
    "link": null,
    "filename": "example.avi",
    "filesize": "30833612",
    "hostDomain": "rapidgator.net",
    "maxchunks": 16,
    "resumable": true,
    "poll_after_seconds": 2,
    "reusedExisting": false
  }
}

Success (200) — file ready on our storage:

{
  "success": true,
  "data": {
    "linkId": "abc123",
    "download_ready": true,
    "remote_status": "done",
    "link": "https://your-proxy/download/abc123/example.avi",
    "filename": "example.avi",
    "filesize": "30833612",
    "hostDomain": "rapidgator.net",
    "maxchunks": 16,
    "resumable": true,
    "poll_after_seconds": 2,
    "reusedExisting": false
  }
}

Traffic: New files consume traffic from your account when the link is created, consistent with the web dashboard. Reusing an existing valid link does not deduct traffic again.

---

4. Poll link until ready

GET /api/external/v1/link/{linkId}

Same authentication as other endpoints. Call this after POST /unrestrict (Section 3 above) until download_ready is true.

Success (200):

{
  "success": true,
  "data": {
    "linkId": "abc123",
    "download_ready": false,
    "remote_status": "downloading",
    "link": null,
    "filename": "example.avi",
    "filesize": "30833612",
    "maxchunks": 16,
    "resumable": true,
    "poll_after_seconds": 2
  }
}

When download_ready is true, link matches the direct download URL described for POST /unrestrict in Section 3 (same field semantics).

Errors: 404 if the link does not exist or does not belong to this API key’s account.

---

Error format

Errors use a stable numeric status so clients never need to parse localized text.

{
  "success": false,
  "status": 52,
  "msg": "Human-readable message (may be localized)",
  "retry_in_seconds": 60
}

retry_in_seconds is present only when a retry makes sense.

Status code reference

---

Notes for integrators

1. Prefer API key auth; do not scrape the login page (Cloudflare / captcha).
2. Poll **/account** at login_check_interval (default 30 min).
3. Refresh **/hosts** on the same schedule; the list tracks host configuration.
4. After **POST /unrestrict**, if download_ready is false, poll **GET /link/{linkId}** every poll_after_seconds until download_ready is true, then start the HTTP download using link.
5. If **remote_status** becomes **error**, stop polling; the transfer failed on our side.
6. Re-use the same **link** when the user pauses and resumes, when possible—we return reusedExisting: true when no extra traffic is charged.
7. Usenet is not supported; do not expect a usenet host entry.

---

Changelog

• v1.3 — Host list payloads include trafficleft and trafficmax_daily (per-platform aggregates from all accounts). GET /hosts/grouped also returns platform. Download-client errors add stable status 107 (HTTP 429) when the upstream pool is temporarily insufficient.
• v1.2 — Added GET /hosts/grouped (one service per row, domains array for alternate hostnames). GET /hosts unchanged aside from later v1.3 fields.
• v1.1 — POST /unrestrict returns linkId, download_ready, remote_status; link is null until ready. Added GET /link/{linkId} for polling.
• v1 — Initial release: account, hosts, unrestrict.