Skip to content
Hoody Documentation
Download Page (.md)

The directory listing endpoints let you manage directories and work with archive files (ZIP, TAR, and compressed TAR variants). You can create new directories, extract archives either fully or selectively, preview archive contents without extraction, read individual files inside archives, download directories as ZIP, and monitor the status of in-progress and completed extractions.

Directory Operations

Section titled “Directory Operations”

MKCOL /{path}

Section titled “MKCOL /{path}”

Create a new directory at the specified path. This uses the WebDAV MKCOL method.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDirectory path to create

This endpoint takes no request body.

The directory was created successfully. No body is returned.

SDK usage

Section titled “SDK usage”
await client.files.directories.create({ path: "projects/2024/reports" });

Archive Extraction

Section titled “Archive Extraction”

GET /{archive}?extract

Section titled “GET /{archive}?extract”

Extract a ZIP, TAR, or compressed TAR archive to a destination directory. An empty ?extract extracts the full archive; ?extract=<path> extracts only entries matching the given path.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
archivepathstringYesPath to the archive file
extractquerystringYesEmpty for full extraction; path for selective (e.g. src/main.rs or lib/)
destquerystringNoDestination directory name (default: archive name)

This endpoint takes no request body.

{
  "success": true,
  "message": "Archive extracted successfully",
  "extraction_id": "8f3a1c20-5b9d-4e7a-bf1e-2d8c6a4f0e9b",
  "destination": "extracted/project-v1.2.3",
  "extracted_files": 248,
  "extracted_bytes": 15728640,
  "selective": false,
  "selective_path": null,
  "error": null
}

SDK usage

Section titled “SDK usage”
// Full extraction
const result = await client.files.archives.extract({
  archive: "uploads/project-v1.2.3.zip",
  extract: "",
  dest: "project-v1.2.3"
});

GET /{archive}?extract_file

Section titled “GET /{archive}?extract_file”

Extract a single file or directory from inside a ZIP, TAR, or compressed TAR archive to a destination directory. Only the specified entry (and its children if a directory) is extracted; the rest of the archive remains untouched.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
archivepathstringYesPath to archive file
extractquerystringYesPath of the file or directory inside the archive to extract (e.g. src/main.rs or lib/)
destquerystringNoDestination directory name (default: archive name)

This endpoint takes no request body.

{
  "success": true,
  "message": "Selective extraction completed",
  "extraction_id": "7b2d8e1f-3c4a-4f8e-9d1c-5a6b7c8d9e0f",
  "destination": "extracted/project-v1.2.3/src",
  "extracted_files": 42,
  "extracted_bytes": 524288,
  "selective": true,
  "selective_path": "src/",
  "error": null
}

SDK usage

Section titled “SDK usage”
const result = await client.files.archives.extractFile({
  archive: "uploads/project-v1.2.3.zip",
  extract: "src/main.rs",
  dest: "project-v1.2.3-src"
});

Archive Inspection

Section titled “Archive Inspection”

GET /{archive}?preview

Section titled “GET /{archive}?preview”

List the contents of a ZIP, TAR, or compressed TAR archive without extracting it, or read a specific file from the archive. An empty ?preview returns a JSON listing of all entries; ?preview=<path> returns the raw content of that file.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
archivepathstringYesPath to archive file
previewquerystringNoEmpty value lists archive contents; non-empty value reads a specific file from the archive (alias: ?contents)
contentsquerystringNoAlias for ?preview

This endpoint takes no request body.

{
  "format": "zip",
  "total_files": 3,
  "total_size": 12500,
  "total_compressed_size": 4200,
  "entries": [
    {
      "path": "src/",
      "is_dir": true,
      "size": 0,
      "compressed_size": 0,
      "modified_time": 1699900000
    },
    {
      "path": "src/main.rs",
      "is_dir": false,
      "size": 8500,
      "compressed_size": 2800,
      "modified_time": 1699900000
    },
    {
      "path": "README.md",
      "is_dir": false,
      "size": 4000,
      "compressed_size": 1400,
      "modified_time": 1699900000
    }
  ]
}

SDK usage

Section titled “SDK usage”
// List archive contents
const listing = await client.files.archives.preview({
  archive: "uploads/project-v1.2.3.zip"
});


// Read a specific file
const file = await client.files.archives.preview({
  archive: "uploads/project-v1.2.3.zip",
  preview: "README.md"
});

GET /{archive}?view_file

Section titled “GET /{archive}?view_file”

Read and return a single file from inside a ZIP, TAR, or compressed TAR archive without extracting the entire archive. Returns the raw file content with an auto-detected MIME type.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
archivepathstringYesPath to archive file
previewquerystringYesPath of the file inside the archive to view (e.g. src/main.rs or README.md)

This endpoint takes no request body.

The raw file content is returned as application/octet-stream (or the auto-detected MIME type) with the bytes of the requested file.

SDK usage

Section titled “SDK usage”
const content = await client.files.archives.viewFile({
  archive: "uploads/project-v1.2.3.zip",
  preview: "README.md"
});

Archive Download

Section titled “Archive Download”

GET /{directory}?zip

Section titled “GET /{directory}?zip”

Create and download a directory as a ZIP archive.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
directorypathstringYesPath of the directory to download
zipquerystringYesEmpty literal value that triggers ZIP download

This endpoint takes no request body.

The directory is returned as a binary application/zip stream.

SDK usage

Section titled “SDK usage”
const zipBlob = await client.files.archives.downloadAsZip({
  directory: "projects/2024/reports"
});

Extraction Status

Section titled “Extraction Status”

GET /?extraction_history

Section titled “GET /?extraction_history”

Get the history of past extractions, including both successful and failed operations.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
extraction_historyquerystringYesEmpty literal value that triggers the history listing

This endpoint takes no request body.

{
  "history": [
    {
      "id": "1f0c2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
      "archive_path": "uploads/project-v1.2.3.zip",
      "dest_path": "extracted/project-v1.2.3",
      "start_time": 1700000000,
      "end_time": 1700000045,
      "status": "completed",
      "total_files": 248,
      "total_bytes": 15728640,
      "extracted_files": 248,
      "extracted_bytes": 15728640,
      "selective": false,
      "selective_path": null,
      "error": null
    },
    {
      "id": "2a1b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
      "archive_path": "uploads/dataset.zip",
      "dest_path": "extracted/dataset",
      "start_time": 1700000100,
      "end_time": 1700000120,
      "status": "failed",
      "total_files": 5000,
      "total_bytes": 209715200,
      "extracted_files": 1523,
      "extracted_bytes": 52428800,
      "selective": true,
      "selective_path": "data/2024/",
      "error": "ZIP_BOMB_DETECTED: suspicious compression ratio"
    }
  ]
}

SDK usage

Section titled “SDK usage”
const history = await client.files.archives.getHistory();

GET /?extractions

Section titled “GET /?extractions”

Get the progress of currently running archive extractions for the requested file path.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
extractionsquerystringYesEmpty literal value that triggers the active extractions listing

This endpoint takes no request body.

{
  "extractions": [
    {
      "id": "3c4d5e6f-7081-92a3-b4c5d6e7f809",
      "archive_path": "uploads/large-dataset.zip",
      "dest_path": "extracted/large-dataset",
      "start_time": 1700000200,
      "status": "extracting",
      "extracted_files": 1523,
      "extracted_bytes": 52428800,
      "total_files": 5000,
      "total_bytes": 209715200,
      "percentage": 30.46,
      "selective": false,
      "selective_path": null
    }
  ]
}

SDK usage

Section titled “SDK usage”
const active = await client.files.archives.listActive();

GET /api/v1/extractions

Section titled “GET /api/v1/extractions”

Get the progress of currently running archive extractions across the entire system.

This endpoint takes no parameters.

This endpoint takes no request body.

{
  "extractions": [
    {
      "id": "4d5e6f70-8192-a3b4-c5d6e7f80910",
      "archive_path": "uploads/large-dataset.zip",
      "dest_path": "extracted/large-dataset",
      "start_time": 1700000200,
      "status": "extracting",
      "extracted_files": 1523,
      "extracted_bytes": 52428800,
      "total_files": 5000,
      "total_bytes": 209715200,
      "percentage": 30.46,
      "selective": false,
      "selective_path": null
    }
  ]
}

SDK usage

Section titled “SDK usage”
const active = await client.files.archives.listGlobal();