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

The directory listing endpoints let you browse, create, and manage directories in a container, preview and extract archive files (ZIP, TAR, and compressed TAR variants), and download directories as ZIP archives. Use these endpoints when you need to inspect archive contents without extracting, perform full or selective extractions, or package directories for download.

All requests target the container-scoped files service at https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu.

Create directory

Section titled “Create directory”

Creates a new directory at the specified path using the WebDAV MKCOL method.

MKCOL /{path}

Section titled “MKCOL /{path}”

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDirectory path to create

Response

Section titled “Response”

Directory created successfully. No response body.

SDK usage

Section titled “SDK usage”
await client.files.directories.create('projects/web-app')

Download directory as ZIP

Section titled “Download directory as ZIP”

Packages a directory into a ZIP archive and returns the binary content.

GET /{directory}?zip

Section titled “GET /{directory}?zip”

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
directorypathstringYesDirectory path to package
zipquerystringYesMarker flag; must be present (empty value)

Response

Section titled “Response”

Returns the ZIP archive as application/zip binary content. Save the response body to a .zip file.

SDK usage

Section titled “SDK usage”
const zipBlob = await client.files.archives.downloadAsZip('projects/web-app', { zip: '' })

Preview archive contents

Section titled “Preview archive contents”

Lists the entries inside an archive without extracting it. With an empty ?preview value, returns a JSON listing of all entries. With ?preview=<path>, returns the raw content of that specific file. The ?contents parameter is an alias for ?preview.

GET /{archive}?preview

Section titled “GET /{archive}?preview”

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

Response

Section titled “Response”
{
  "format": "zip",
  "total_files": 3,
  "total_size": 15728640,
  "total_compressed_size": 8388608,
  "entries": [
    {
      "path": "src/",
      "is_dir": true,
      "size": 0,
      "compressed_size": 0,
      "modified_time": 1705312800,
      "permissions": 493,
      "entry_type": "directory"
    },
    {
      "path": "src/index.js",
      "is_dir": false,
      "size": 4096,
      "compressed_size": 2048,
      "modified_time": 1705312800,
      "permissions": 420,
      "entry_type": "file"
    },
    {
      "path": "build/output",
      "is_dir": false,
      "size": 0,
      "compressed_size": 0,
      "modified_time": 1705312800,
      "permissions": 420,
      "entry_type": "symlink",
      "link_target": "/var/cache/output"
    }
  ]
}

SDK usage

Section titled “SDK usage”
// List archive contents
const contents = await client.files.archives.preview('backup-2024-01-15.zip', { preview: '' })


// Read a specific file from the archive
const readme = await client.files.archives.preview('backup-2024-01-15.zip', { preview: 'README.md' })

View file from archive

Section titled “View file from archive”

Reads and returns a single file from inside an archive without extracting the entire archive. Returns the raw file content with an auto-detected MIME type. Use this endpoint to inspect individual files before deciding to extract the whole archive.

GET /{archive}?view_file

Section titled “GET /{archive}?view_file”

Parameters

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

Response

Section titled “Response”

Returns the file content as application/octet-stream binary data. The MIME type is auto-detected based on the file extension when possible.

SDK usage

Section titled “SDK usage”
const fileData = await client.files.archives.viewFile('backup-2024-01-15.zip', { preview: 'README.md' })

Extract archive

Section titled “Extract archive”

Extracts a ZIP, TAR, or compressed TAR archive to a destination directory. Pass an empty ?extract value to extract everything, or pass ?extract=<path> to perform a selective extraction of matching entries.

GET /{archive}?extract

Section titled “GET /{archive}?extract”

Parameters

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

Response

Section titled “Response”
{
  "success": true,
  "message": "Archive extracted successfully",
  "extraction_id": "550e8400-e29b-41d4-a716-446655440000",
  "destination": "backup-2024-01-15",
  "extracted_files": 1247,
  "extracted_bytes": 15728640,
  "error": null,
  "selective": false,
  "selective_path": null
}

SDK usage

Section titled “SDK usage”
// Full extraction
const result = await client.files.archives.extract('backup-2024-01-15.zip', { extract: '', dest: 'restored-backup' })


// Selective extraction
const selective = await client.files.archives.extract('source.tar.gz', { extract: 'src/' })

Extract file from archive

Section titled “Extract file from archive”

Extracts 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, leaving other archive contents untouched.

GET /{archive}?extract_file

Section titled “GET /{archive}?extract_file”

Parameters

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

Response

Section titled “Response”
{
  "success": true,
  "message": "Selected entries extracted successfully",
  "extraction_id": "550e8400-e29b-41d4-a716-446655440000",
  "destination": "source",
  "extracted_files": 42,
  "extracted_bytes": 1048576,
  "error": null,
  "selective": true,
  "selective_path": "src/"
}

SDK usage

Section titled “SDK usage”
const result = await client.files.archives.extractFile('source.tar.gz', { extract: 'src/', dest: 'source' })

Extraction history

Section titled “Extraction history”

Returns a history of past extractions, including both successful and failed operations.

GET /?extraction_history

Section titled “GET /?extraction_history”

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
extraction_historyquerystringYesMarker flag; must be present (empty value)

Response

Section titled “Response”
{
  "history": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "archive_path": "backup-2024-01-15.zip",
      "dest_path": "backup-2024-01-15",
      "status": "completed",
      "selective": false,
      "selective_path": null,
      "start_time": 1705312800,
      "end_time": 1705312845,
      "extracted_files": 1247,
      "extracted_bytes": 15728640,
      "total_files": 1247,
      "total_bytes": 15728640,
      "error": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "archive_path": "broken-archive.tar.gz",
      "dest_path": "broken-archive",
      "status": "failed",
      "selective": true,
      "selective_path": "data/",
      "start_time": 1705226400,
      "end_time": 1705226412,
      "extracted_files": 3,
      "extracted_bytes": 8192,
      "total_files": 1200,
      "total_bytes": 31457280,
      "error": "Path traversal attempt blocked"
    }
  ]
}

SDK usage

Section titled “SDK usage”
const history = await client.files.archives.getHistory({ extraction_history: '' })

List active extractions

Section titled “List active extractions”

Returns progress information for currently running archive extractions.

GET /?extractions

Section titled “GET /?extractions”

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
extractionsquerystringYesMarker flag; must be present (empty value)

Response

Section titled “Response”
{
  "extractions": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "archive_path": "large-dataset.zip",
      "dest_path": "large-dataset",
      "status": "running",
      "selective": false,
      "selective_path": null,
      "start_time": 1705312800,
      "extracted_files": 524,
      "extracted_bytes": 7340032,
      "total_files": 3500,
      "total_bytes": 52428800,
      "percentage": 14.0
    }
  ]
}

SDK usage

Section titled “SDK usage”
const active = await client.files.archives.listActive({ extractions: '' })

List active extractions (API)

Section titled “List active extractions (API)”

Returns progress information for currently running archive extractions via the versioned API path.

GET /api/v1/extractions

Section titled “GET /api/v1/extractions”

This endpoint takes no parameters.

Response

Section titled “Response”
{
  "extractions": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "archive_path": "large-dataset.zip",
      "dest_path": "large-dataset",
      "status": "running",
      "selective": false,
      "selective_path": null,
      "start_time": 1705312800,
      "extracted_files": 524,
      "extracted_bytes": 7340032,
      "total_files": 3500,
      "total_bytes": 52428800,
      "percentage": 14.0
    }
  ]
}

SDK usage

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