---
title: "Create volume from archive"
method: POST
path: "/volumes/from-archive"
---

# Create volume from archive

`POST /volumes/from-archive`

Creates a new volume pre-populated with content from a tar.gz archive.
The archive is streamed directly into the volume's root directory.

## Query parameters

- `name` string, required
- `size_gb` integer, required
- `id` string
- `tags` Tags — User-defined key-value tags.

## Response `201`

Volume created

- Volume
  - `id` string, required — Unique identifier
  - `name` string, required — Volume name
  - `size_gb` integer, required — Size in gigabytes
  - `tags` Tags — User-defined key-value tags.
  - `attachments` VolumeAttachment[] — List of current attachments (empty if not attached)
    - `instance_id` string, required — ID of the instance this volume is attached to
    - `mount_path` string, required — Mount path in the guest
    - `readonly` boolean, required — Whether the attachment is read-only
  - `created_at` string, date-time, required — Creation timestamp (RFC3339)

## Other responses

- `400` — Bad request (invalid data or archive too large)
- `401` — Unauthorized
- `409` — Conflict - volume with this ID already exists
- `500` — Internal server error

## Changes

> 74 revisions in range; 1 could not be searched.

- **2026-03-09** `d3b8f05f7a0f` — 2 warning, 2 info
  - deleted the `query` request parameter `metadata`
  - removed the optional property `metadata` from the response with the `201` status
  - added the new optional `query` request parameter `tags`
  - added the optional property `tags` to the response with the `201` status
- **2026-03-07** `48572ed07140` — 2 info
  - added the new optional `query` request parameter `metadata`
  - added the optional property `metadata` to the response with the `201` status
- **2026-01-30** `cf9805637aaf` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kernel/apis/hypeman-api/changes/volumes/from-archive/post.md)

---

[API](https://skmtc.dev/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.dev/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/hypeman-api/revisions/b4642bb950dc/schema)