Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Downloading Files

Section titled “Downloading Files”

The Downloading Files API lets you fetch files from remote URLs directly into a container’s filesystem, monitor in-flight transfers, and review historical download activity. Use these endpoints to programmatically ingest external resources into container directories.

Download file from remote URL

Section titled “Download file from remote URL”

GET /{directory}?download

Initiates a download from a remote URL into the specified directory inside the container’s filesystem. The download runs asynchronously on the server and returns a unique identifier that can be used to track progress and review history.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
directorypathstringYesDestination directory
downloadquerystringYesURL to download from
filenamequerystringNoCustom filename for downloaded file
timeoutqueryintegerNoDownload timeout in seconds. Default: 300

Example

Section titled “Example”
Terminal window
curl -X GET "https://proj_8f3a2b1c-ctnr_4d7e9f12-files-1.us-east-1.containers.hoody.icu/Downloads?download=https%3A%2F%2Ffiles.example.com%2Fdata.csv&filename=renamed-data.csv&timeout=600"

Responses

Section titled “Responses”
{
  "success": true,
  "message": "Download completed successfully",
  "download_id": "7c4e2b89-1a3f-4d5e-9c2b-8f6e3a7d4b1e",
  "filename": "renamed-data.csv",
  "path": "/files/Downloads/renamed-data.csv",
  "error": null
}

List active downloads (per directory)

Section titled “List active downloads (per directory)”

GET /{directory}?downloads

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
directorypathstringYesDirectory to query for active downloads
downloadsquerystringYesSentinel value (empty string) that activates the listing

Example

Section titled “Example”
Terminal window
curl -X GET "https://proj_8f3a2b1c-ctnr_4d7e9f12-files-1.us-east-1.containers.hoody.icu/Downloads?downloads="

Response 200

Section titled “Response 200”
{
  "downloads": [
    {
      "id": "7c4e2b89-1a3f-4d5e-9c2b-8f6e3a7d4b1e",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/files/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "status": "downloading",
      "start_time": 1718304123,
      "current_size": 5242880,
      "expected_size": 10485760,
      "progress_percentage": 50.0
    },
    {
      "id": "9b1e7c44-5a8d-4f62-83c1-2e7d9a5b3f08",
      "directory": "Downloads",
      "filename": "report.pdf",
      "file_path": "/files/Downloads/report.pdf",
      "url": "https://files.example.com/report.pdf",
      "status": "starting",
      "start_time": 1718304189,
      "current_size": 0,
      "expected_size": null,
      "progress_percentage": null
    }
  ]
}

List active downloads (global)

Section titled “List active downloads (global)”

GET /api/v1/downloads

Returns progress information for every download currently running in the container, regardless of which directory it was started in.

This endpoint takes no parameters.

Example

Section titled “Example”
Terminal window
curl -X GET "https://proj_8f3a2b1c-ctnr_4d7e9f12-files-1.us-east-1.containers.hoody.icu/api/v1/downloads"

Response 200

Section titled “Response 200”
{
  "downloads": [
    {
      "id": "7c4e2b89-1a3f-4d5e-9c2b-8f6e3a7d4b1e",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/files/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "status": "downloading",
      "start_time": 1718304123,
      "current_size": 5242880,
      "expected_size": 10485760,
      "progress_percentage": 50.0
    }
  ]
}

Download history

Section titled “Download history”

GET /?download_history

Returns a chronological history of completed and failed downloads. Each entry includes the original URL, target path, timing, byte count, and terminal status.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
download_historyquerystringYesSentinel value (empty string) that activates the history listing

Example

Section titled “Example”
Terminal window
curl -X GET "https://proj_8f3a2b1c-ctnr_4d7e9f12-files-1.us-east-1.containers.hoody.icu/?download_history="

Response 200

Section titled “Response 200”
{
  "history": [
    {
      "id": "7c4e2b89-1a3f-4d5e-9c2b-8f6e3a7d4b1e",
      "directory": "Downloads",
      "filename": "data.csv",
      "file_path": "/files/Downloads/data.csv",
      "url": "https://files.example.com/data.csv",
      "status": "completed",
      "start_time": 1718304123,
      "end_time": 1718304156,
      "total_bytes": 10485760,
      "error": null
    },
    {
      "id": "2f8a3d61-9c4b-4e57-8a2d-1b9f7c6e5d04",
      "directory": "Archives",
      "filename": "missing-archive.zip",
      "file_path": "/files/Archives/missing-archive.zip",
      "url": "https://files.example.com/missing-archive.zip",
      "status": "failed",
      "start_time": 1718304001,
      "end_time": 1718304003,
      "total_bytes": null,
      "error": "The URL returned 404 Not Found"
    }
  ]
}