Downloading Files

Download files from remote URLs and track their progress. These endpoints let you initiate downloads, monitor active transfers, and review past download history.

Download from URL

`GET /{directory}?download`

Initiates a download from a remote URL to the specified directory on the server. The download runs asynchronously and returns a download_id you can use to track progress via the active downloads endpoint.

Parameters

Name	In	Type	Required	Description
`directory`	path	string	Yes	Destination directory
`download`	query	string	Yes	URL to download from
`filename`	query	string	No	Custom filename for downloaded file
`timeout`	query	integer	No	Download timeout in seconds (default: `300`)

curl -X GET "https://api.example.com/Downloads?download=https%3A%2F%2Ffiles.example.com%2Fdata.csv" \
  -H "Authorization: Bearer <token>"

const result = await client.files.downloads.fetch({
  directory: "Downloads",
  download: "https://files.example.com/data.csv",
  filename: "renamed-data.csv",
  timeout: 600
});

{
  "download_id": "7a3f8b12-4d5e-4a1b-9c8f-2e6d7f8a9b0c",
  "filename": "renamed-data.csv",
  "path": "Downloads/renamed-data.csv",
  "success": true,
  "message": "Download started",
  "error": null
}

{
  "download_id": "7a3f8b12-4d5e-4a1b-9c8f-2e6d7f8a9b0c",
  "filename": "data.csv",
  "path": "Downloads/data.csv",
  "success": false,
  "message": "Download failed",
  "error": "INVALID_URL"
}

Error Code	Title	Description	Resolution
`INVALID_URL`	Invalid URL	The provided URL is malformed or invalid	Verify URL format is correct and includes protocol (http:// or https://)
`DOMAIN_BLOCKED`	Domain not allowed	This domain is blocked by server’s download domain restrictions	Contact administrator to whitelist this domain or use allowed domains
`DOWNLOAD_TIMEOUT`	Download timeout	Download exceeded the configured timeout period	Try again with longer timeout or check network connectivity
`REMOTE_FILE_NOT_FOUND`	Remote file not found	The URL returned 404 Not Found	Verify the URL is correct and the file exists
`NETWORK_ERROR`	Network error	Failed to connect to remote server or download was interrupted	Check network connectivity and try again

{
  "success": false,
  "error": "DOWNLOAD_FORBIDDEN"
}

Error Code	Title	Description	Resolution
`DOWNLOAD_FORBIDDEN`	Download operation not allowed	Server is not configured to allow downloading from URLs	Contact administrator to enable —allow-download flag

List Active Downloads (Directory)

`GET /{directory}?downloads`

Returns progress information for downloads currently running in the specified directory.

Parameters

Name	In	Type	Required	Description
`directory`	path	string	Yes	Directory to check for active downloads
`downloads`	query	string	Yes	Pass an empty string to list active downloads

curl -X GET "https://api.example.com/Downloads?downloads=" \
  -H "Authorization: Bearer <token>"

const active = await client.files.downloads.listActive({
  directory: "Downloads",
  downloads: ""
});

{
  "downloads": [
    {
      "id": "7a3f8b12-4d5e-4a1b-9c8f-2e6d7f8a9b0c",
      "filename": "dataset.zip",
      "file_path": "Downloads/dataset.zip",
      "directory": "Downloads",
      "url": "https://files.example.com/dataset.zip",
      "status": "downloading",
      "current_size": 52428800,
      "expected_size": 104857600,
      "progress_percentage": 50.0,
      "start_time": 1700000000
    }
  ]
}

List Active Downloads (Global)

`GET /api/v1/downloads`

Returns progress information for all downloads currently running on the server, across every directory.

This endpoint takes no parameters.

curl -X GET "https://api.example.com/api/v1/downloads" \
  -H "Authorization: Bearer <token>"

const active = await client.files.downloads.listGlobal();

{
  "downloads": [
    {
      "id": "7a3f8b12-4d5e-4a1b-9c8f-2e6d7f8a9b0c",
      "filename": "dataset.zip",
      "file_path": "Downloads/dataset.zip",
      "directory": "Downloads",
      "url": "https://files.example.com/dataset.zip",
      "status": "downloading",
      "current_size": 52428800,
      "expected_size": 104857600,
      "progress_percentage": 50.0,
      "start_time": 1700000000
    },
    {
      "id": "8b4c9d23-5e6f-5b2c-ad90-3f7e8a9b0c1d",
      "filename": "report.pdf",
      "file_path": "Documents/report.pdf",
      "directory": "Documents",
      "url": "https://docs.example.com/report.pdf",
      "status": "starting",
      "current_size": 0,
      "expected_size": null,
      "progress_percentage": null,
      "start_time": 1700000050
    }
  ]
}

Download History

`GET /?download_history`

Returns a history of past downloads, including both completed and failed transfers.

Parameters

Name	In	Type	Required	Description
`download_history`	query	string	Yes	Pass an empty string to retrieve download history

curl -X GET "https://api.example.com/?download_history=" \
  -H "Authorization: Bearer <token>"

const history = await client.files.downloads.getHistory();

{
  "history": [
    {
      "id": "7a3f8b12-4d5e-4a1b-9c8f-2e6d7f8a9b0c",
      "filename": "dataset.zip",
      "file_path": "Downloads/dataset.zip",
      "directory": "Downloads",
      "url": "https://files.example.com/dataset.zip",
      "status": "completed",
      "total_bytes": 104857600,
      "start_time": 1700000000,
      "end_time": 1700000030,
      "error": null
    },
    {
      "id": "9c5d0e34-6f70-6c3d-be01-4a8f9b0c1d2e",
      "filename": "missing.csv",
      "file_path": "Downloads/missing.csv",
      "directory": "Downloads",
      "url": "https://files.example.com/missing.csv",
      "status": "failed",
      "total_bytes": null,
      "start_time": 1700000100,
      "end_time": 1700000105,
      "error": "REMOTE_FILE_NOT_FOUND"
    }
  ]
}