Skip to main content
The /download endpoint allows you to start new downloads and query the status of existing downloads.

​
POST /download

Start a new download.

​
Request Body

​
url
string
required
The URL of the file to download. This is the only required parameter.
​
filename
string
Custom filename for the downloaded file. If not provided, Surge will extract the filename from the URL or Content-Disposition header.
​
path
string
Destination directory path. Can be absolute or relative depending on the relative_to_default_dir flag.
​
relative_to_default_dir
boolean
default:false
If true, the path parameter is treated as relative to the default download directory configured in settings.
​
mirrors
array
Array of mirror URLs to use for accelerated downloads. Surge will use these mirrors in addition to the primary URL.
["https://mirror1.example.com/file.zip", "https://mirror2.example.com/file.zip"]
​
skip_approval
boolean
default:false
Skip duplicate download checks and user prompts. Useful for automated downloads from trusted sources like browser extensions.
​
headers
object
Custom HTTP headers to include in download requests. Useful for authentication, cookies, or other request customization.
{
  "Cookie": "session=abc123",
  "User-Agent": "Custom/1.0"
}

​
Response

Returns a JSON object with the download ID and status:
​
id
string
Unique identifier for the download. Use this ID with other endpoints to control the download.
​
status
string
Initial status of the download, typically "queued".
​
url
string
The URL being downloaded.

​
Examples

curl -X POST http://localhost:1700/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.zip"}'

​
Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "url": "https://example.com/file.zip"
}

​
GET /download

Query the status of a specific download.

​
Query Parameters

​
id
string
required
The unique download ID returned when the download was created.

​
Response

Returns detailed status information about the download:
​
id
string
Unique identifier for the download.
​
url
string
The URL being downloaded.
​
filename
string
The filename of the download.
​
dest_path
string
Full absolute path to the destination file.
​
total_size
integer
Total file size in bytes.
​
downloaded
integer
Number of bytes downloaded so far.
​
progress
number
Download progress as a percentage (0-100).
​
speed
number
Current download speed in MB/s.
​
status
string
Current status: "queued", "downloading", "paused", "completed", or "error".
​
error
string
Error message if status is "error".
​
eta
integer
Estimated time remaining in seconds.
​
connections
integer
Number of active connections.
​
added_at
integer
Unix timestamp when the download was added.
​
time_taken
integer
Total time taken in milliseconds (for completed downloads).
​
avg_speed
number
Average download speed in bytes/sec (for completed downloads).

​
Example

curl "http://localhost:1700/download?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/file.zip",
  "filename": "file.zip",
  "dest_path": "/home/user/downloads/file.zip",
  "total_size": 104857600,
  "downloaded": 52428800,
  "progress": 50.0,
  "speed": 5.2,
  "status": "downloading",
  "eta": 10,
  "connections": 8,
  "added_at": 1709481600
}

​
Error Responses