Volumes
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:volumes
include_deleted?booleanInclude retired (deleted) volumes in the listing.
Volumes in the project
application/json- response
Response envelope for GET /volumes.
volumes*array<>curl -X GET 'https://example.com/volumes'{ "volumes": [ { "conflicts": null, "created_at": "2019-08-24T14:15:22Z", "error_reason": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_manifest_id": "string", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "options": {}, "size_gb": 0, "state": "string", "type": "string", "updated_at": "2019-08-24T14:15:22Z", "used_bytes": 0, "used_bytes_at": "2019-08-24T14:15:22Z" } ]}AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: write:volumes
application/json- body
bucket?null|name*stringsize_gb?|Per-volume scratch size (GiB); absent => 100. Disk volumes only — supplying it on a bucket volume is a 400.
int32type?|disk (the default) or bucket. blockmount is accepted as the
pre-rename spelling of disk.
Volume created (ready immediately)
application/json- response
A volume as returned by the API. last_manifest_id/conflicts are read
best-effort from the CAS store on detail routes only (never on list).
conflicts?unknownConcurrent-write conflicts recorded on the latest manifest (audit trail).
created_at*stringdate-timeerror_reason?string|nullid*stringuuidlast_manifest_id?|Blockmount CAS pointer, read-through on detail routes (best-effort).
last_used_at?|date-timename*stringoptions?Per-type options, namespaced by type (PLAN-VOLUME-TYPES.md §1): {} for
a disk volume, {"bucket": {...}} for a bucket one. Credentials appear
as the project-secret NAMES that were supplied, never as values —
values are write-only across the whole API.
size_gb?|Scratch capacity in GiB. Disk volumes only — a bucket volume has no
capacity of its own and reports null.
int32state*stringtype*stringupdated_at*stringdate-timeused_bytes?|Real (logical) usage in bytes: sum of committed file sizes, hardlink
groups counted once. Cached from runner events.volume.* reports; absent
until the first report lands (never written / pre-feature volume).
int64used_bytes_at?|When the cached used_bytes was observed by the runner.
date-timecurl -X POST 'https://example.com/volumes' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "conflicts": null, "created_at": "2019-08-24T14:15:22Z", "error_reason": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_manifest_id": "string", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "options": {}, "size_gb": 0, "state": "string", "type": "string", "updated_at": "2019-08-24T14:15:22Z", "used_bytes": 0, "used_bytes_at": "2019-08-24T14:15:22Z"}AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:volumes
id*stringVolume id or name
id_only?booleanResolve the path strictly as a UUID, without a name fallback.
Volume detail (CAS fields best-effort)
application/json- response
A volume as returned by the API. last_manifest_id/conflicts are read
best-effort from the CAS store on detail routes only (never on list).
conflicts?unknownConcurrent-write conflicts recorded on the latest manifest (audit trail).
created_at*stringdate-timeerror_reason?string|nullid*stringuuidlast_manifest_id?|Blockmount CAS pointer, read-through on detail routes (best-effort).
last_used_at?|date-timename*stringoptions?Per-type options, namespaced by type (PLAN-VOLUME-TYPES.md §1): {} for
a disk volume, {"bucket": {...}} for a bucket one. Credentials appear
as the project-secret NAMES that were supplied, never as values —
values are write-only across the whole API.
size_gb?|Scratch capacity in GiB. Disk volumes only — a bucket volume has no
capacity of its own and reports null.
int32state*stringtype*stringupdated_at*stringdate-timeused_bytes?|Real (logical) usage in bytes: sum of committed file sizes, hardlink
groups counted once. Cached from runner events.volume.* reports; absent
until the first report lands (never written / pre-feature volume).
int64used_bytes_at?|When the cached used_bytes was observed by the runner.
date-timecurl -X GET 'https://example.com/volumes/string'{ "conflicts": null, "created_at": "2019-08-24T14:15:22Z", "error_reason": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_manifest_id": "string", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "options": {}, "size_gb": 0, "state": "string", "type": "string", "updated_at": "2019-08-24T14:15:22Z", "used_bytes": 0, "used_bytes_at": "2019-08-24T14:15:22Z"}AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: delete:volumes
id*stringVolume id or name
id_only?booleanResolve the path strictly as a UUID, without a name fallback.
Deletion complete
application/json- response
Response for DELETE /volumes/{id}.
id*stringuuidstate*stringdeleting while accepted work is pending; deleted once complete.
curl -X DELETE 'https://example.com/volumes/string'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "state": "string"}