---
title: "Create, extract, or list an archive"
method: POST
path: "/v1/archive"
tags: ["Files"]
---

# Create, extract, or list an archive

`POST /v1/archive`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/archive`
- Auth: HTTP bearer

Archive utility for `.zip`, `.tar`, and `.tar.gz` (format inferred from
extension when not explicit). `create` packs `source_paths` into
`archive_path`; `extract` writes contents under `output_dir` (defaults to the
archive's parent dir); `list` enumerates entries without extracting.
All paths must be absolute. Optional `password` for supported formats.

## Request body

- ArchiveRequest
  - `action` 'create' | 'extract' | 'list', required
  - `archive_path` string, required: Absolute path to the archive file.
  - `format` 'zip' | 'tar' | 'tar.gz': Archive format. Inferred from `archive_path` extension when omitted.
  - `source_paths` string[]: Absolute paths to pack. Required for `action=create`.
  - `output_dir` string: Absolute extraction directory. Defaults to the archive's parent dir. `action=extract` only.
  - `password` string: Optional password for supported formats.

## Response `200`

Action-specific response (shape varies by action)

- ArchiveResponse
  - `archivePath` string, required
  - `format` string, required
  - `entryCount` integer: Number of entries (set on `create` and `list`).
  - `extractedDir` string: Extraction directory (set on `extract`).
  - `entries` object[]: Entry list (set on `list`).
    - `name` string
    - `size` integer
    - `isDirectory` boolean

## Other responses

- `400`: Invalid request
- `404`: Resource not found
- `500`: Archive operation failed

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)