Create a volume

POST/api/v1/volumes

Creates a volume, usually in a few seconds; one from a backup takes longer, by its size. Poll Get a volume until its state is created, then attach it. The volume is billed by the hour for its size, attached or not.

Request body

Field	Type	Description
display_name	string, optional	Name of the volume
size_gb	integerrequired	Size, GB: up to 5,000 on standard, up to 10,000 on enterprise
storage_class_id	integerrequired	Disk id, from List disks
source_snapshot_id	string, optional	Make the volume from a snapshot of another volume
source_backup_id	string, optional	Make the volume from a backup of another volume

Example request

curl -X POST "https://platform.serverscamp.com/api/v1/volumes" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "data",
    "size_gb": 100,
    "storage_class_id": 18
  }'

import os, requests

token = os.environ["API_TOKEN"]
r = requests.post(
    f"https://platform.serverscamp.com/api/v1/volumes",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "display_name": "data",
      "size_gb": 100,
      "storage_class_id": 18
    },
)
r.raise_for_status()
print(r.json())

const r = await fetch(`https://platform.serverscamp.com/api/v1/volumes`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "display_name": "data",
    "size_gb": 100,
    "storage_class_id": 18
  }),
});
console.log(r.status, await r.json());

curl -X POST "https://platform.serverscamp.com/api/v1/volumes" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "pg-data",
    "size_gb": 500,
    "storage_class_id": 20
  }'

import os, requests

token = os.environ["API_TOKEN"]
r = requests.post(
    f"https://platform.serverscamp.com/api/v1/volumes",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "display_name": "pg-data",
      "size_gb": 500,
      "storage_class_id": 20
    },
)
r.raise_for_status()
print(r.json())

const r = await fetch(`https://platform.serverscamp.com/api/v1/volumes`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "display_name": "pg-data",
    "size_gb": 500,
    "storage_class_id": 20
  }),
});
console.log(r.status, await r.json());

curl -X POST "https://platform.serverscamp.com/api/v1/volumes" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "data-copy",
    "size_gb": 100,
    "storage_class_id": 18,
    "source_snapshot_id": "5e8b2c41-0d7a-4f39-b6e2-91c3a8d4f017"
  }'

import os, requests

token = os.environ["API_TOKEN"]
r = requests.post(
    f"https://platform.serverscamp.com/api/v1/volumes",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "display_name": "data-copy",
      "size_gb": 100,
      "storage_class_id": 18,
      "source_snapshot_id": "5e8b2c41-0d7a-4f39-b6e2-91c3a8d4f017"
    },
)
r.raise_for_status()
print(r.json())

const r = await fetch(`https://platform.serverscamp.com/api/v1/volumes`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "display_name": "data-copy",
    "size_gb": 100,
    "storage_class_id": 18,
    "source_snapshot_id": "5e8b2c41-0d7a-4f39-b6e2-91c3a8d4f017"
  }),
});
console.log(r.status, await r.json());

Answer

Status 201 with this body.

Field	Type	Description
disk_uuid	stringrequired	Volume id
display_name	string, optional	The name you gave
size_gb	integerrequired	Size, GB
status	stringrequired	queued: poll Get a volume until it is created

{
  "disk_uuid": "c7a1e3f9-52b8-4d06-9e41-8b3f2a6d0c75",
  "display_name": "data",
  "size_gb": 100,
  "status": "queued"
}

Wait until it is ready

The answer comes at once and the work runs in the background, usually for a few seconds. Get a volume shows how far it got in its state field.

Check the state

Ask Get a volume with the volume's id; the field to watch is state:

curl "https://platform.serverscamp.com/api/v1/volumes/$DISK_UUID" \
  -H "Authorization: Bearer $API_TOKEN"

state	What it means
`creating`	The volume is being made; one from a backup also shows provision_phase and provision_pct
`created`	Ready. With vm_uuid set it is attached to that server, without it the volume is free
`attaching, detaching, resizing`	The change runs
`failed`	Something went wrong. Write to support with the volume id

Wait in a loop

Ask every few seconds until the state is no longer one of the busy ones, and stop on failed.

# DISK_UUID: disk_uuid of the volume, from the answer above
BUSY=" pending queued creating provisioning attaching attach_queued detaching detach_queued resizing deleting deprovisioning delete_queued "
while true; do
  VOL=$(curl -s "https://platform.serverscamp.com/api/v1/volumes/$DISK_UUID" -H "Authorization: Bearer $API_TOKEN")
  STATE=$(echo "$VOL" | jq -r .state)
  echo "$STATE"
  case "$STATE" in failed|error) echo "volume $STATE"; exit 1;; esac
  case "$BUSY" in *" $STATE "*) ;; *) [ "$(echo "$VOL" | jq -r '.provision_phase // "ready"')" = ready ] && break;; esac
  sleep 5
done

# disk_uuid: disk_uuid of the volume, from the answer above
import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}
busy = {"pending", "queued", "creating", "provisioning", "attaching", "attach_queued", "detaching", "detach_queued", "resizing", "deleting", "deprovisioning", "delete_queued"}
while True:
    vol = requests.get(f"https://platform.serverscamp.com/api/v1/volumes/{disk_uuid}", headers=headers).json()
    print(vol["state"])
    if vol["state"] in ("failed", "error"):
        raise SystemExit("volume " + vol["state"])
    if vol["state"] not in busy and (vol.get("provision_phase") or "ready") == "ready":
        break
    time.sleep(5)

// diskUuid: disk_uuid of the volume, from the answer above
const headers = { Authorization: `Bearer ${process.env.API_TOKEN}` };
const busy = new Set(['pending', 'queued', 'creating', 'provisioning', 'attaching', 'attach_queued', 'detaching', 'detach_queued', 'resizing', 'deleting', 'deprovisioning', 'delete_queued']);
for (;;) {
  const vol = await (await fetch(`https://platform.serverscamp.com/api/v1/volumes/${diskUuid}`, { headers })).json();
  console.log(vol.state);
  if (vol.state === 'failed' || vol.state === 'error') throw new Error('volume ' + vol.state);
  if (!busy.has(vol.state) && (vol.provision_phase ?? 'ready') === 'ready') break;
  await new Promise((ok) => setTimeout(ok, 5000));
}

The bash version needs jq.

Errors

Status	When
`400`	A disk or size that is not accepted
`401`	No token, or a token that is not valid
`402`	The balance is too low
`403`	The volume limit of the account is reached
`404`	No such snapshot or backup in your account
`422`	The body or a parameter is not what the operation takes

Every operation can also answer 401 without a valid token. All errors