Volumes

A volume is a disk that outlives the machine it is attached to. An app with a volume runs exactly one machine; a deploy stops that machine before the new one starts. A computer’s home is a volume named <computer>-home.

Endpoints

• POST /v1/volumes: Creates a volume
• GET /v1/volumes: The organization’s volumes
• PATCH /v1/volumes/:id: Resizes a volume or changes its settings
• DELETE /v1/volumes/:id: Deletes a volume that is not attached
• DELETE /v1/volumes/:id/attachment: Detaches the volume from its app

POST /v1/volumes

Creates a volume.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Request body

JSON, the shape CreateVolumeRequest of the contract.

Field	Type	Required	Description
name	string	required
sizeGb	integer	optional	Size in GB. 1 to 500, default 10.
mountPath	string	optional	default "/data".
class	standard | durable	optional	A named size instead of vcpus; the two must not contradict each other. default "standard".
flushIntervalS	integer	optional	15 to 86400.

Example request

curl -X POST "https://api.rytiv.app/v1/volumes" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"data"}'

Response

201 with the volume:

{
  "id": "<id>",
  "name": "data",
  "orgId": "<orgId>",
  "sizeGb": 1,
  "mountPath": "<mountPath>",
  "class": "standard",
  "flushIntervalS": 86400,
  "leaseGen": 0,
  "durableGen": 0,
  "createdAt": "2026-10-21T09:00:00Z"
}

Field	Type	Present	Description
id	string	always	The volume’s id.
name	string	always
orgId	string	always	The organization that owns it.
sizeGb	integer	always	Its size. 1 to 500.
mountPath	string	always
class	standard | durable	always	A named size instead of vcpus; the two must not contradict each other. default "standard".
flushIntervalS	integer	always	2 to 86400, default 86400.
machineId	string	if set
appName	string	if set
leaseHost	string	if set
leaseGen	integer	always	0 to 9007199254740991, default 0.
durableGen	integer	always	0 to 9007199254740991, default 0.
durableAt	string (ISO 8601)	if set	When the last copy to durable storage completed.
walDurableAt	string (ISO 8601)	if set
createdAt	string (ISO 8601)	always	When it was created.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
409	name-taken	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).

GET /v1/volumes

The organization’s volumes.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Example request

curl -X GET "https://api.rytiv.app/v1/volumes" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a list of volumes, each:

[
  {
    "id": "<id>",
    "name": "data",
    "orgId": "<orgId>",
    "sizeGb": 1,
    "mountPath": "<mountPath>",
    "class": "standard",
    "flushIntervalS": 86400,
    "leaseGen": 0,
    "durableGen": 0,
    "createdAt": "2026-10-21T09:00:00Z"
  }
]

Field	Type	Present	Description
id	string	always	The volume’s id.
name	string	always
orgId	string	always	The organization that owns it.
sizeGb	integer	always	Its size. 1 to 500.
mountPath	string	always
class	standard | durable	always	A named size instead of vcpus; the two must not contradict each other. default "standard".
flushIntervalS	integer	always	2 to 86400, default 86400.
machineId	string	if set
appName	string	if set
leaseHost	string	if set
leaseGen	integer	always	0 to 9007199254740991, default 0.
durableGen	integer	always	0 to 9007199254740991, default 0.
durableAt	string (ISO 8601)	if set	When the last copy to durable storage completed.
walDurableAt	string (ISO 8601)	if set
createdAt	string (ISO 8601)	always	When it was created.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.

PATCH /v1/volumes/:id

Resizes a volume or changes its settings.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
id	The volume’s id.

Request body

JSON, the shape UpdateVolumeRequest of the contract.

Field	Type	Required	Description
sizeGb	integer	optional	Size in GB. 1 to 500.
flushIntervalS	integer	optional	15 to 86400.

Example request

curl -X PATCH "https://api.rytiv.app/v1/volumes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sizeGb":1}'

Response

200 with the volume:

{
  "id": "<id>",
  "name": "data",
  "orgId": "<orgId>",
  "sizeGb": 1,
  "mountPath": "<mountPath>",
  "class": "standard",
  "flushIntervalS": 86400,
  "leaseGen": 0,
  "durableGen": 0,
  "createdAt": "2026-10-21T09:00:00Z"
}

Field	Type	Present	Description
id	string	always	The volume’s id.
name	string	always
orgId	string	always	The organization that owns it.
sizeGb	integer	always	Its size. 1 to 500.
mountPath	string	always
class	standard | durable	always	A named size instead of vcpus; the two must not contradict each other. default "standard".
flushIntervalS	integer	always	2 to 86400, default 86400.
machineId	string	if set
appName	string	if set
leaseHost	string	if set
leaseGen	integer	always	0 to 9007199254740991, default 0.
durableGen	integer	always	0 to 9007199254740991, default 0.
durableAt	string (ISO 8601)	if set	When the last copy to durable storage completed.
walDurableAt	string (ISO 8601)	if set
createdAt	string (ISO 8601)	always	When it was created.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/volumes/:id

Deletes a volume that is not attached.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
id	The volume’s id.

Example request

curl -X DELETE "https://api.rytiv.app/v1/volumes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.
409	volume-attached

DELETE /v1/volumes/:id/attachment

Detaches the volume from its app.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
id	The object’s id.

Example request

curl -X DELETE "https://api.rytiv.app/v1/volumes/<id>/attachment" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.