# Downloading Files

**Page:** api/files/downloading

[Download Raw Markdown](./api/files/downloading.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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`) |



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


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


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


```json
{
  "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 |


```json
{
  "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 |




The server must be started with the `--allow-download` flag for downloads to be permitted. Contact your administrator if you receive a `DOWNLOAD_FORBIDDEN` error.


## 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 |



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


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


```json
{
  "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.



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


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


```json
{
  "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 |



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


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


```json
{
  "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"
    }
  ]
}
```