Volumes¶

Persistent disks you can attach to a machine. Data on a volume survives the machine being destroyed and recreated.

Base URL: https://api.sistemo.io · all requests require authentication.

List volumes¶

GET /v1/volumes

Scope: read or full.

curl https://api.sistemo.io/v1/volumes \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

Create a volume¶

POST /v1/volumes

Scope: full.

Field	Type	Notes
`name`	string	Label
`size_gb`	int	Size in GB — minimum 5, cannot be resized later

curl -X POST https://api.sistemo.io/v1/volumes \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"data","size_gb":10}'

created_at / updated_at are zero in the create response

A create returns "0001-01-01T00:00:00Z" for both — Go's zero time, not a real timestamp. The values are correct everywhere else, so read them from a subsequent GET rather than from the create response. Observed 2026-09-22.

Attach a volume¶

POST /v1/volumes/{id}/attach

Scope: full. The machine must be stopped and on the same host.

Stop the machine first, or this is a 409

Attaching to a running machine is refused:

{ "code": "conflict", "detail": "stop the machine before attaching a volume" }

A disk cannot appear under a booted guest, so this is a real constraint rather than a formality. The full sequence is stop → attach → start:

# 1. Stop the machine.
curl -X POST "https://api.sistemo.io/v1/machines/$MACHINE/stop" \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

# 2. Attach (now allowed).
curl -X POST "https://api.sistemo.io/v1/volumes/$VOL/attach" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"machine_id":"'"$MACHINE"'"}'

# 3. Start it again. The disk appears as the next drive (/dev/vdb for the
#    first data volume) and is NOT mounted for you.
curl -X POST "https://api.sistemo.io/v1/machines/$MACHINE/start" \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

Then mount it inside the guest — see Persist data with volumes.

Detach a volume¶

POST /v1/volumes/{id}/detach

Scope: full. The machine must be stopped here too — same reason, same 409 if it is not.

Delete a volume¶

DELETE /v1/volumes/{id}

Scope: full. The volume must not be attached.

Durability test¶

Write a string to a volume, destroy the machine, reattach to a new one — the data survives:

# Machine stopped → attach → start. First data disk is /dev/vdb (already ext4).
# Nothing auto-mounts it:
mkdir -p /mnt/data && mount /dev/vdb /mnt/data
echo "hello $(date)" > /mnt/data/test.txt
# destroy A, attach to B, start B, mount again, then:
cat /mnt/data/test.txt   # the string is still there

See also: Machines · the SDK close(preserve_storage=True) keeps a machine's root disk as a volume.