# Directory Listing

**Page:** api/files/directories

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

---

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



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

### `MKCOL /{path}`

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

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Directory path to create |

This endpoint takes no request body.



The directory was created successfully. No body is returned.


```json
{
  "success": false,
  "error": "Directory creation is not allowed on this server"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `UPLOAD_FORBIDDEN` | Directory creation not allowed | Server is not configured to allow directory creation | Contact administrator to enable --allow-upload flag |
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | User account does not have write permissions for this path | Contact administrator for write permissions |


```json
{
  "success": false,
  "error": "Directory already exists at the specified path"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DIRECTORY_EXISTS` | Directory already exists | A directory with this name already exists at the specified path | Choose a different name or delete the existing directory first |



#### SDK usage

```ts
await client.files.directories.create({ path: "projects/2024/reports" });
```

## Archive Extraction

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


Supported formats include `zip`, `tar`, `tar.gz`, `tar.bz2`, and `tar.xz`.


#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `archive` | path | string | Yes | Path to the archive file |
| `extract` | query | string | Yes | Empty for full extraction; path for selective (e.g. `src/main.rs` or `lib/`) |
| `dest` | query | string | No | Destination directory name (default: archive name) |

This endpoint takes no request body.



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


```json
{
  "success": false,
  "message": "Invalid archive format",
  "extraction_id": "8f3a1c20-5b9d-4e7a-bf1e-2d8c6a4f0e9b",
  "destination": "",
  "extracted_files": 0,
  "extracted_bytes": 0,
  "selective": false,
  "selective_path": null,
  "error": "File is not a valid archive or format is unsupported"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ARCHIVE_FORMAT` | Invalid archive format | File is not a valid archive or format is unsupported | Verify file is a supported archive format (zip, tar, tar.gz, tar.bz2, tar.xz) |
| `ARCHIVE_TOO_LARGE` | Archive exceeds size limit | Archive total size exceeds configured maximum extraction size | Contact administrator to increase extraction size limit or extract manually |
| `TOO_MANY_FILES` | Too many files in archive | Archive contains more files than allowed maximum | Contact administrator to increase file count limit or extract in smaller batches |
| `ZIP_BOMB_DETECTED` | Potential zip bomb detected | Archive has suspicious compression ratio indicating potential zip bomb | Verify archive source is trusted, contact administrator if legitimate |
| `PATH_TRAVERSAL_BLOCKED` | Path traversal attempt blocked | Archive contains files attempting to escape extraction directory | Archive may be malicious, verify source and re-create archive without path traversal |


```json
{
  "success": false,
  "error": "Archive extraction is not enabled on this server"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `EXTRACTION_FORBIDDEN` | Extraction not allowed | Server is not configured to allow archive extraction | Contact administrator to enable --allow-extract flag |



#### SDK usage

```ts
// 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`

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

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `archive` | path | string | Yes | Path to archive file |
| `extract` | query | string | Yes | Path of the file or directory inside the archive to extract (e.g. `src/main.rs` or `lib/`) |
| `dest` | query | string | No | Destination directory name (default: archive name) |

This endpoint takes no request body.



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


```json
{
  "success": false,
  "message": "No matching entries",
  "extraction_id": "7b2d8e1f-3c4a-4f8e-9d1c-5a6b7c8d9e0f",
  "destination": "",
  "extracted_files": 0,
  "extracted_bytes": 0,
  "selective": true,
  "selective_path": "missing/path/",
  "error": "No entries matched the specified path"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ARCHIVE_FORMAT` | Invalid archive format | File is not a valid archive or format is unsupported | Verify file is a supported archive format (zip, tar, tar.gz, tar.bz2, tar.xz) |
| `INVALID_SELECTIVE_PATH` | Invalid entry path | The entry path is invalid (empty, absolute, contains traversal, or null bytes) | Use a relative path without `..` components (e.g. `src/main.rs` or `lib/`) |
| `NO_MATCHING_ENTRIES` | No matching entries | No entries in the archive matched the specified path | Use the preview endpoint to list archive contents and verify the entry path |
| `PATH_TRAVERSAL_BLOCKED` | Path traversal attempt blocked | Archive contains files attempting to escape extraction directory | Archive may be malicious, verify source and re-create archive without path traversal |


```json
{
  "success": false,
  "error": "Archive extraction is not enabled on this server"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `EXTRACTION_FORBIDDEN` | Extraction not allowed | Server is not configured to allow archive extraction | Contact administrator to enable --allow-extract flag |


```json
{
  "success": false,
  "error": "Archive file not found"
}
```



#### SDK usage

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

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


The `?contents` query parameter is an alias for `?preview` and behaves identically.


#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `archive` | path | string | Yes | Path to archive file |
| `preview` | query | string | No | Empty value lists archive contents; non-empty value reads a specific file from the archive (alias: `?contents`) |
| `contents` | query | string | No | Alias for `?preview` |

This endpoint takes no request body.



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


```json
{
  "success": false,
  "error": "Corrupted archive"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ARCHIVE_FORMAT` | Invalid archive format | File is not a valid ZIP, TAR, or compressed TAR archive | Verify file is a valid archive and format is supported (zip, tar, tar.gz, tar.bz2, tar.xz) |
| `CORRUPTED_ARCHIVE` | Corrupted archive | Archive file is corrupted or incomplete | Re-download or re-upload the archive file |


```json
{
  "success": false,
  "error": "Archive entry is password-protected"
}
```


```json
{
  "success": false,
  "error": "Archive file or entry not found"
}
```


```json
{
  "success": false,
  "error": "File too large for preview (max 100MB)"
}
```



#### SDK usage

```ts
// 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`

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.


Use this endpoint to inspect individual files inside an archive before deciding to extract the whole archive.


#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `archive` | path | string | Yes | Path to archive file |
| `preview` | query | string | Yes | Path 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.


```json
{
  "success": false,
  "error": "Invalid entry path"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ARCHIVE_FORMAT` | Invalid archive format | File is not a valid ZIP, TAR, or compressed TAR archive | Verify file is a valid archive and format is supported (zip, tar, tar.gz, tar.bz2, tar.xz) |
| `INVALID_SELECTIVE_PATH` | Invalid entry path | The entry path is invalid (empty, absolute, contains traversal, or null bytes) | Use a relative path without `..` components (e.g. `src/main.rs`) |


```json
{
  "success": false,
  "error": "Archive entry is password-protected"
}
```


```json
{
  "success": false,
  "error": "Archive file or entry not found"
}
```


```json
{
  "success": false,
  "error": "File too large for preview"
}
```



#### SDK usage

```ts
const content = await client.files.archives.viewFile({
  archive: "uploads/project-v1.2.3.zip",
  preview: "README.md"
});
```

## Archive Download

### `GET /{directory}?zip`

Create and download a directory as a ZIP archive.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `directory` | path | string | Yes | Path of the directory to download |
| `zip` | query | string | Yes | Empty literal value that triggers ZIP download |

This endpoint takes no request body.



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


```json
{
  "success": false,
  "error": "Archive download is not allowed on this server"
}
```



#### SDK usage

```ts
const zipBlob = await client.files.archives.downloadAsZip({
  directory: "projects/2024/reports"
});
```

## Extraction Status

### `GET /?extraction_history`

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

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `extraction_history` | query | string | Yes | Empty literal value that triggers the history listing |

This endpoint takes no request body.



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

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

### `GET /?extractions`

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

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `extractions` | query | string | Yes | Empty literal value that triggers the active extractions listing |

This endpoint takes no request body.



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

```ts
const active = await client.files.archives.listActive();
```

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



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

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