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 (from Storage Master)

GET /api/external/v1/hosts

The hostname list is served by Storage Master and proxied by the portal so it always matches the adapters deployed on Master.

Success (200):

{
  "success": true,
  "data": {
    "supportedhosts": [
      {
        "host": "rapidgator.net",
        "maxChunks": 16,
        "maxDownloads": 3,
        "resumable": true,
        "currently_working": true
      }
    ],
    "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). Prefer GET /api/external/v1/hosts/grouped if you want one row per file-hosting service with alternate domains listed together.

---

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 Master’s list for that service), a sorted domains array of all URL hostnames for that service, and merged limits (maxChunks / maxDownloads are maxima across domains; resumable and currently_working require all underlying rows to match).

Success (200):

{
  "success": true,
  "data": {
    "supportedhosts": [
      {
        "host": "rapidgator.net",
        "domains": ["rapidgator.net", "rg.to"],
        "maxChunks": 16,
        "maxDownloads": 3,
        "resumable": true,
        "currently_working": true
      }
    ],
    "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 Master 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.2 — Added **GET /hosts/grouped** (one service per row, domains array for alternate hostnames). **GET /hosts** unchanged.
• 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 (Master-sourced), unrestrict.