Skip to main content
POST
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

Body

application/json
tag
string
required

Name of the tag to set. Tags are case-sensitive. Setting a tag that already exists overwrites it, and the version it pointed at before stays reachable by digest.

Pattern: ^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$
Example:

"nightly"

version
string
required

Version to set the tag on. Address it with :<tag> for a tag, @<digest> for a full content digest or a prefix of at least 12 hexadecimal characters, or head for the version a reference with no tag or digest resolves to.

Example:

"head"

expires_at
string<date-time> | null

Time at which the tag expires, in ISO 8601 format, with a UTC offset. It must be in the future and at most ten years ahead. Omit it for a tag with no expiration time of its own. Omitting it also clears the expiration time of an existing tag. Version or volume expiration still deletes the tag. Do not specify it when setting head.

expected_sequence
integer | null

Revision the volume is expected to be at. When set, the request fails with a conflict if the volume has changed since. Take the value from volume_sequence.

Required range: x >= 0

Response

200 - application/json
namespace
string
required

Namespace the volume belongs to, in lowercase.

volume
string
required

Name of the volume, in lowercase.

tag
string
required

Name of the tag that was set, with its original capitalization.

digest
string
required

Content digest of the version the tag points at, as b3:<hex>.

version_ref
string
required

Full address of the tagged version, as bdn:<namespace>/<volume>@<digest>. Paste it into a config.yaml to pin this version, even if the tag is later set on another version.

volume_sequence
integer
required

Revision of the volume after the tag was set.

expires_at
string<date-time> | null
required

Tag expiration time in ISO 8601 format. Null when the tag has no expiration time of its own.