Downloading Files

Download Page (.md)

The Files Downloads API lets you fetch remote files into a server-side directory, monitor in-flight downloads, and review historical download activity. Use these endpoints to pull external content into the platform’s filesystem or audit past transfers.

Download file from remote URL

Download a file from a remote URL to the server.

`GET /{directory}?download`

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`

This endpoint accepts no request body.

Response

{
  "success": true,
  "download_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "filename": "renamed-data.csv",
  "path": "/home/user/Downloads/renamed-data.csv",
  "message": "Download started",
  "error": null
}

{
  "success": false,
  "download_id": "",
  "filename": "data.csv",
  "path": "",
  "message": "Download failed",
  "error": "The provided URL is malformed or invalid"
}

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": "Server is not configured to allow downloading from URLs"
}

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

SDK usage

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

List active downloads in a directory

Get progress of currently running downloads scoped to a single directory.

`GET /{directory}?downloads`

Parameters

Name	In	Type	Required	Description
`directory`	path	string	Yes	Directory to scope the listing to
`downloads`	query	string	Yes	Reserved query parameter — pass an empty string

This endpoint accepts no request body.

Response

{
  "downloads": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/home/user/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "current_size": 5242880,
      "expected_size": 10485760,
      "progress_percentage": 50.0,
      "start_time": 1700000000,
      "status": "downloading"
    }
  ]
}

SDK usage

const active = await client.files.downloads.listActive("Downloads", "");

List all active downloads

Get progress of currently running downloads across every directory.

`GET /api/v1/downloads`

This endpoint takes no parameters.

This endpoint accepts no request body.

Response

{
  "downloads": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/home/user/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "current_size": 5242880,
      "expected_size": 10485760,
      "progress_percentage": 50.0,
      "start_time": 1700000000,
      "status": "downloading"
    }
  ]
}

SDK usage

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

Get download history

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

`GET /?download_history`

Parameters

Name	In	Type	Required	Description
`download_history`	query	string	Yes	Reserved query parameter — pass an empty string

This endpoint accepts no request body.

Response

{
  "history": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/home/user/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "start_time": 1700000000,
      "end_time": 1700000015,
      "total_bytes": 10485760,
      "status": "completed",
      "error": null
    }
  ]
}

SDK usage

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