Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Path Parameters

volume_namespace
string
required
volume_name
string
required

Response

200 - application/json
namespace
string
required

Namespace the volume belongs to, in lowercase.

name
string
required

Name of the volume, in lowercase.

version_ref
string
required

Full address of the volume, as bdn:<namespace>/<volume>. Paste this into the bdn.mounts section of a config.yaml.

sequence
integer
required

Revision counter for the volume, incremented on every commit, tag change, delete, and restore. A tag or version that expires leaves without changing it; the next write then increments it once. Use it to detect that a volume was written to.

updated_at
string<date-time>
required

When the volume was last written to, in ISO 8601 format. An expiry does not update it.

expires_at
string<date-time> | null
required

When the whole volume expires, in ISO 8601 format. At that instant every live version is deleted, every tag drops, and the volume leaves the volume listing; each version then stays restorable until its recovery deadline passes. Null for a volume that never expires.

head
VolumeVersionSummaryV1 · object | null
required

Version that the reserved head tag points at, which a reference with no tag or digest resolves to. Never an expiring version. Null when the volume has no head, or when your API key cannot read it.

tags
VolumeTagV1 · object[]
required

Tags on the volume that your API key can read. A tag with expires_at leaves this list at that instant.

tag_count
integer
required

Total number of tags on the volume, which can exceed the length of tags when your API key cannot read all of them. Counts only tags that have not expired.

versions_alive
integer
required

Number of versions that have not been deleted or expired.

versions_tombstoned
integer
required

Number of versions that have been deleted or expired and are still within their recovery window.

versions_untagged
integer
required

Number of live versions that no tag points at.

versions_expiring
integer
required

Number of live versions with an expiry still ahead of them. A version that has already expired counts in versions_tombstoned instead.

versions_earliest_expires_at
string<date-time> | null
required

Earliest expiry among the live versions, in ISO 8601 format. Null when no live version is scheduled to expire.