Downloading Files

Use these endpoints to fetch files from remote URLs into the container’s filesystem, monitor in-flight transfers, and review download history. Every endpoint targets the container’s files service and supports bearer-token authentication.

The base URL for all operations on this page is https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com.

Start a download from a remote URL

Fetch a file from a remote URL and store it in a directory on the container. The transfer runs asynchronously; poll the active-downloads endpoints or check the history to track its outcome.

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

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/Downloads?download=https%3A%2F%2Ffiles.example.com%2Fdata.csv&filename=renamed-data.csv&timeout=600" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "success": true,
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "renamed-data.csv",
  "path": "/home/user/Downloads/renamed-data.csv",
  "message": "Download started successfully",
  "error": null
}

{
  "success": false,
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "missing.pdf",
  "path": "",
  "message": "Failed to download file",
  "error": "HTTP 404: Not Found"
}

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

Monitor active downloads

Two endpoints expose in-flight transfers: a directory-scoped view and a container-wide view. Both return the same progress shape.

`GET /{directory}?downloads`

Parameters

Name	In	Type	Required	Description
`directory`	path	string	Yes	Directory to scope the listing to
`downloads`	query	string	Yes	Sentinel value; pass the empty string `""`

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/Downloads?downloads=" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "downloads": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://files.example.com/large.zip",
      "filename": "large.zip",
      "directory": "Downloads",
      "file_path": "/home/user/Downloads/large.zip",
      "status": "downloading",
      "start_time": 1717171717,
      "current_size": 524288,
      "expected_size": 10485760,
      "progress_percentage": 5.0
    }
  ]
}

`GET /api/v1/downloads`

This endpoint takes no parameters.

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/downloads" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.downloads.listGlobal();

{
  "downloads": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://files.example.com/large.zip",
      "filename": "large.zip",
      "directory": "Downloads",
      "file_path": "/home/user/Downloads/large.zip",
      "status": "downloading",
      "start_time": 1717171717,
      "current_size": 524288,
      "expected_size": 10485760,
      "progress_percentage": 5.0
    },
    {
      "id": "a3f1c2d4-5e6b-47c8-9d01-23456789abcd",
      "url": "https://mirror.example.org/dataset.tar.gz",
      "filename": "dataset.tar.gz",
      "directory": "Data",
      "file_path": "/home/user/Data/dataset.tar.gz",
      "status": "starting",
      "start_time": 1717171800,
      "current_size": 0,
      "expected_size": null,
      "progress_percentage": null
    }
  ]
}

Review download history

Retrieve the historical record of completed and failed transfers.

`GET /?download_history`

Parameters

Name	In	Type	Required	Description
`download_history`	query	string	Yes	Sentinel value; pass the empty string `""`

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/?download_history=" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.downloads.getHistory("");

{
  "history": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://files.example.com/data.csv",
      "filename": "data.csv",
      "directory": "Downloads",
      "file_path": "/home/user/Downloads/data.csv",
      "status": "completed",
      "start_time": 1717171717,
      "end_time": 1717171725,
      "total_bytes": 1048576,
      "error": null
    },
    {
      "id": "b7c8d9e0-1a2b-3c4d-5e6f-7890abcdef01",
      "url": "https://files.example.com/missing.pdf",
      "filename": "missing.pdf",
      "directory": "Downloads",
      "file_path": "/home/user/Downloads/missing.pdf",
      "status": "failed",
      "start_time": 1717171800,
      "end_time": 1717171803,
      "total_bytes": null,
      "error": "HTTP 404: Not Found"
    }
  ]
}