PricingConsole

Management API: Volumes

Last updated 3 November 2026

View .md

The account's Volumes (contracts/machines/volume-v1.json): disks in one region, each bound to at most one Machine of that region through the Machine's volumes. The overview covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.

List the account's Volumes

GET /v1/volumes · CLI: tonbo volume list

Needs account.read, which owner, admin and member hold. A narrowed key may call it.

The account's Volumes (contracts/machines/volume-v1.json) from every region, by name, including those being deleted until their purge ends; unavailable_regions names the regions whose Volumes could not be read. An account holds at most quotas.volumes_per_account Volumes, so the list is not paged. Served whatever machines.open says; a narrowed key never reaches a Volume.

Response

StatusAnswer
200Volumes
FieldTypeRequiredDescription
dataarray of VolumeyesThe account's Volumes in every region it could read, by name.
unavailable_regionsarray of stringyesThe regions whose Volumes could not be read; their Volumes are missing from data.
HeaderStatusDescription
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429Seconds before the client should retry.
Example 200 body
{
  "data": [
    {
      "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
      "name": "data",
      "region": "xx-example-1",
      "size_gib": 20,
      "machine": null,
      "state": "available",
      "live_bytes": 0,
      "last_commit_at": null,
      "created_at": "2027-02-15T09:30:00Z",
      "writes_held": null
    }
  ],
  "unavailable_regions": [
    "<unavailable_regions>"
  ]
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.NoUse a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)

Retries

  • A read: sending it again changes nothing.
  • 429 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/volumes" \
  -H "Authorization: Bearer $TONBO_API_KEY"

Create a Volume

POST /v1/volumes · CLI: tonbo volume create

Needs machines.write, which owner, admin and member hold. A narrowed key may not.

A Volume in region, created available, of size_gib (1 to 100, fixed for its life). size_gib may be left out (contracts/machines/volume-v1.json size): in a region whose new Volumes take the account's size, the Volume is then the account's current total (contracts/billing/account-unlocks-v1.json volumes), at most 100 GiB; elsewhere it is 10 GiB. An account that has never bought credit holds one Volume, in any region, of at most its total (contracts/billing/account-unlocks-v1.json volumes): a second create answers 402 payment_required, and a size past the total the same naming size_gib; Volumes it already holds past one keep working. A Machine of the same region binds it through its spec volumes. It needs machines.write, a region where Machines are offered to the account (422 region_not_offered otherwise) and the account's Volumes there (contracts/machines/volume-v1.json flag, the same 422 otherwise). An account whose credit is exhausted answers 402 payment_required and nothing is written. A name another live Volume of the account holds, in any region, answers 409 conflict, and so does a Volume past the account's quotas.volumes_per_account. for_machine names the Machine the Volume is made for, as the console's create form does for the disk it makes, which then deletes it by default when that Machine is deleted (contracts/machines/machine-v2.json delete_volume); a replay must name the same one. The answer is 201 with the new Volume, and 200 when the same Idempotency-Key replays it; the key reused for another request answers 409. Both carry Location, the Volume's URL. Billing counts the Volume's live bytes, never its size.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringyesA value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409. 1 to 255 characters.

Request body

application/json, required. Unknown fields are refused.

The fields below are the contract’s, with their types and limits; Things to know explains what each one does.

FieldTypeRequiredDescription
namestringyes1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
regionstringyesMatches ^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$.
size_gibintegerno1 to 100.
for_machinestringno1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".

Response

StatusAnswer
200The Volume an earlier request with this Idempotency-Key created
201The new Volume
FieldTypeRequiredDescription
dataVolumeyesThe Volume.
HeaderStatusDescription
Location200, 201The Volume's URL, https://api.tonbo.dev/v1/volumes/{name}.
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429, 503Seconds before the client should retry.
Example 200 body
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
402payment_requiredThe account’s balance is zero, so nothing new is created. Also, before an account has paid (contracts/billing/account-unlocks-v1.json): a request that makes a Machine port public on an account with neither a card nor bought credit (errors names ports), and a Volume create by an account that has never bought credit that already holds a Volume in any region (volumes.never_paid_max_count, one), or of a Volume larger than its total, volumes.never_paid_total_gib without a card and volumes.card_bound_total_gib with one (size_gib).NoAdd credit on Usage & billing, which lifts all of them. Or add a card there (adding one charges nothing) for a public port or a larger Volume; then send the request again. (more)
403forbiddenThe key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.NoUse a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
409conflictThe name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.NoPick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
409idempotency_conflictThe Idempotency-Key was already sent with a different request.NoSend the request with a new Idempotency-Key, or send the request the key was first used for. (more)
422region_not_offeredThe resource is not offered in the region named, or in the account’s default region. Nothing was written.NoName a region where it is offered; GET /v1/regions lists the regions and what each offers. (more)
422validation_errorA parameter, header or body field breaks its rule; errors names each field.NoCorrect the fields errors names; the operation’s reference gives each one’s rule. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
503region_unavailableThe region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.After Retry-AfterSend the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)

Retries

  • Send a new Idempotency-Key with each request and the same one when you send it again: a repeat answers what the first request did, and the key reused for a different request answers 409 (see Idempotency).
  • 429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/volumes" \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"data","region":"xx-example-1"}'

Read a Volume

GET /v1/volumes/{name} · CLI: tonbo volume show

Needs account.read, which owner, admin and member hold. A narrowed key may call it.

A Volume of the account: the live one of the name, or else the latest being deleted. machine names the Machine it is bound to, live_bytes what the chunk-store meter bills and last_commit_at its last committed flush. writes_held is non-null while the Machine's writes to it are held until a copy catches up, with since when and why; a held write is never failed. A region this server cannot reach answers 503 region_unavailable when the Volume is in no region it read.

Parameters

NameInTypeRequiredDescription
namepathstringyesThe Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".

Response

StatusAnswer
200The Volume
FieldTypeRequiredDescription
dataVolumeyesThe Volume.
HeaderStatusDescription
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429, 503Seconds before the client should retry.
Example 200 body
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.NoUse a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
404not_foundNo live resource of the key’s account has that name or id, or the key is narrowed away from it.NoCheck the name, and that the key belongs to the account that holds it; list the resources to see what exists. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
503region_unavailableThe region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.After Retry-AfterSend the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)

Retries

  • A read: sending it again changes nothing.
  • 429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/volumes/<name>" \
  -H "Authorization: Bearer $TONBO_API_KEY"

Delete a Volume

DELETE /v1/volumes/{name} · CLI: tonbo volume delete

Needs machines.write, which owner, admin and member hold. A narrowed key may not.

A Volume bound to a Machine answers 409 conflict: remove it from the Machine first (volumes: []). Otherwise the Volume enters deleting and is purged: its data key is destroyed first, then its objects and its ledger (contracts/machines/volume-v1.json deletion); its name is free at once. The answer is 202 with the Volume being deleted, and again for a Volume already deleting. There are no Volume snapshots or backups, so a deleted Volume cannot be recovered.

Parameters

NameInTypeRequiredDescription
namepathstringyesThe Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".

Response

StatusAnswer
202The Volume, being deleted
FieldTypeRequiredDescription
dataVolumeyesThe Volume.
HeaderStatusDescription
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429, 503Seconds before the client should retry.
Example 202 body
{
  "data": {
    "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
    "name": "data",
    "region": "xx-example-1",
    "size_gib": 20,
    "machine": null,
    "state": "available",
    "live_bytes": 0,
    "last_commit_at": null,
    "created_at": "2027-02-15T09:30:00Z",
    "writes_held": null
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.NoUse a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
404not_foundNo live resource of the key’s account has that name or id, or the key is narrowed away from it.NoCheck the name, and that the key belongs to the account that holds it; list the resources to see what exists. (more)
409conflictThe name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.NoPick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
503region_unavailableThe region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.After Retry-AfterSend the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)

Retries

  • It takes no Idempotency-Key; its description above says what sending it again does.
  • 429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS -X DELETE "https://api.tonbo.dev/v1/volumes/<name>" \
  -H "Authorization: Bearer $TONBO_API_KEY"

Read a Volume's metrics over a window

GET /v1/volumes/{name}/metrics · CLI: tonbo volume metrics

Needs account.read, which owner, admin and member hold. A narrowed key may call it.

One Volume's metrics over a window ending with the current step, by the UTC hour or day: its guest I/O (read_bytes, write_bytes, read_ops, write_ops, trim_ops), counted as its daemon served its Machine's requests, 0 in a step with none, and stored_bytes, what its files held at the step's last sample (taken every 5 minutes, written when it changed), carried from the step before when the step has none and null before its first. Hours go back 8 days and days 92. The I/O updates about every 30 seconds while the Volume is attached and starts with the hour its recording went live. The Volume is the live one of the name, or else the latest being deleted. The latency series (read_latency_p50_ms, read_latency_p99_ms, write_latency_p50_ms, write_latency_p99_ms) are the median and 99th percentile time the Volume's daemon took to answer the guest's successful reads and writes, from a request's arrival to its reply, write holds included; the account's are read from every Volume's merged histograms, never an average of percentiles, and a step with no timed request is null. Display only, never billed: what a Volume is billed for is /usage. Takes the parameters of getVolumeMetrics; stored_bytes here also answers hourly.

Parameters

NameInTypeRequiredDescription
namepathstringyesThe Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
seriesquerystringnoThe series to answer, comma-separated, of stored_bytes, read_bytes, write_bytes, read_ops, write_ops, trim_ops, read_latency_p50_ms, read_latency_p99_ms, write_latency_p50_ms and write_latency_p99_ms; every series when omitted. Matches ^(stored_bytes|read_bytes|write_bytes|read_ops|write_ops|trim_ops|read_latency_p50_ms|read_latency_p99_ms|write_latency_p50_ms|write_latency_p99_ms)(,(stored_bytes|read_bytes|write_bytes|read_ops|write_ops|trim_ops|read_latency_p50_ms|read_latency_p99_ms|write_latency_p50_ms|write_latency_p99_ms))*$.
windowqueryone of "24h", "7d", "30d" or "90d"no24h, the last 24 UTC hours, hourly; or the last 7, 30 or 90 UTC days, today included, daily (7d also hourly with granularity=hour).
granularityqueryone of "hour" or "day"nohour or day: the step, with from and to (day when omitted), or with window=7d.
fromquerystringnoWith to, instead of window, the window's first step, a UTC hour for granularity=hour or a UTC midnight (or a date) by the day.
toquerystringnoWith from, the step boundary the window ends at, exclusive, at most 8 days after from by the hour or 92 by the day, and the end of the current step at the latest.

Response

StatusAnswer
200The Volume's metrics
FieldTypeRequiredDescription
dataVolumeNameMetricsyes
HeaderStatusDescription
WWW-Authenticate401Authentication scheme required by this API.
Retry-After429, 503Seconds before the client should retry.
Example 200 body
{
  "data": {
    "name": "<name>",
    "region": "<region>",
    "granularity": "hour",
    "from": "2026-11-02T09:30:00.000Z",
    "to": "2026-11-02T09:30:00.000Z",
    "as_of": "2026-11-02T09:30:00.000Z",
    "points": [
      {
        "start": "2026-11-02T09:30:00.000Z",
        "stored_bytes": 0,
        "read_bytes": 0,
        "write_bytes": 0,
        "read_ops": 0,
        "write_ops": 0,
        "trim_ops": 0,
        "read_latency_p50_ms": 0,
        "read_latency_p99_ms": 0,
        "write_latency_p50_ms": 0,
        "write_latency_p99_ms": 0,
        "partial": false
      }
    ]
  }
}

Errors

StatusCodeWhenSend againWhat to do
401exchange_requiredThe key acts as an Agent, and an Agent’s key is never sent itself.NoExchange the key for a token at the endpoint the answer’s token_endpoint names, and send the token as Authorization: Bearer. (more)
401unauthenticatedThe request carries no key or token, or one that is invalid, expired or revoked.NoSend a valid key, or a token that has not expired, as Authorization: Bearer. (more)
403forbiddenThe key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.NoUse a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
404not_foundNo live resource of the key’s account has that name or id, or the key is narrowed away from it.NoCheck the name, and that the key belongs to the account that holds it; list the resources to see what exists. (more)
422validation_errorA parameter, header or body field breaks its rule; errors names each field.NoCorrect the fields errors names; the operation’s reference gives each one’s rule. (more)
429rate_limitedThe key or the account sent more requests than its rate allows.After Retry-AfterWait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
503region_unavailableThe region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.After Retry-AfterSend the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)

Retries

  • A read: sending it again changes nothing.
  • 429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
Request
curl -sS "https://api.tonbo.dev/v1/volumes/<name>/metrics" \
  -H "Authorization: Bearer $TONBO_API_KEY"

Objects

Volume

A Volume as contracts/machines/volume-v1.schema.json $defs.volume defines it.

The fields below are the contract’s, with their types and limits; Things to know explains what each one does.

FieldTypeRequiredDescription
idstringyesMatches ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$.
namestringyes1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
regionstringyesMatches ^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$.
size_gibintegeryes1 to 100.
machineobject or nullyes
machine.idstringyesMatches ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$.
machine.namestringyes1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
stateone of "available", "bound", "attached" or "deleting"yes
live_bytesintegeryes0 to 9007199254740991.
last_commit_atstring (date-time) or nullyesMatches Z$.
created_atstring (date-time)yesMatches Z$.
writes_heldobject or nullyes
writes_held.sincestring (date-time)yesMatches Z$.
writes_held.reasonone of "budget", "copy_bound" or "upload_budget"yes
for_machinestring or nullno1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
Example Volume
{
  "id": "0f6c2a8e-3b1d-4c55-9a7e-2d4b6f8e1a90",
  "name": "data",
  "region": "xx-example-1",
  "size_gib": 20,
  "machine": null,
  "state": "available",
  "live_bytes": 0,
  "last_commit_at": null,
  "created_at": "2027-02-15T09:30:00Z",
  "writes_held": null
}

VolumeNameMetrics

FieldTypeRequiredDescription
namestringyesThe Volume's name.
regionstringyesThe Volume's region.
granularityone of "hour" or "day"yeshour or day: one point per UTC hour or day.
fromstring (date-time)yesThe window's first instant, a UTC hour or midnight.
tostring (date-time)yesThe instant the window ends, exclusive.
as_ofstring (date-time) or nullyesWhen the latest step read was last written; null when the window holds none.
pointsarray of VolumeMetricPointyesEvery step of the window, oldest first.
Example VolumeNameMetrics
{
  "name": "<name>",
  "region": "<region>",
  "granularity": "hour",
  "from": "2026-11-02T09:30:00.000Z",
  "to": "2026-11-02T09:30:00.000Z",
  "as_of": "2026-11-02T09:30:00.000Z",
  "points": [
    {
      "start": "2026-11-02T09:30:00.000Z",
      "stored_bytes": 0,
      "read_bytes": 0,
      "write_bytes": 0,
      "read_ops": 0,
      "write_ops": 0,
      "trim_ops": 0,
      "read_latency_p50_ms": 0,
      "read_latency_p99_ms": 0,
      "write_latency_p50_ms": 0,
      "write_latency_p99_ms": 0,
      "partial": false
    }
  ]
}