Box Versions API

Box versions represent new releases for boxes, and contain both information about the changes in that version as well as being the parent object for providers, which contain the eventual box file.

Release Flow

When a version is first created, its status is set to unreleased. This allows you to update the providers and description prior to release.

Once a version is ready to release, you can then make a request to move it to an active state. Versions that have been "released" can then no longer be deleted. Instead, you should "revoke" a released version, setting the status as revoked. This stops access to the version from Vagrant, but maintains the history of the version.

You cannot modify the status attribute directly, so their are seperate endpoints to revoke and release versions.

Box Version Attributes

Attribute Description Required
version The version number, typically incrementing a previous version. We validate this version string based on Semantic Versioning. Yes
description Markdown text used as a full-length and in-depth description of the version, typically for denoting changes introduced. Markdown is parsed according to GitHub Flavored Markdown. There is no maximum length. No

Actions

The following actions can be perfomed on this resource.

Show
GET /api/v1/box/:username/:name/version/:number
Create
POST /api/v1/box/:username/:name/versions
Update
PUT /api/v1/box/:username/:name/version/:number
Delete
DELETE /api/v1/box/:username/:name/version/:number
Release
PUT /api/v1/box/:username/:name/version/:number/release
Revoke
PUT /api/v1/box/:username/:name/version/:number/revoke

Examples

Create a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/versions \
    -X POST \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d version[version]='1.0'

Retrieve a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/version/1 \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Update a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/version/1 \
    -X PUT \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d version[description]='updating the description'

Destroy a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/version/1 \
    -X DELETE \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Release a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/version/test/release \
    -X PUT \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Revoke a version

$ curl https://atlas.hashicorp.com/api/v1/box/acmeinc/test/version/1/revoke \
    -X PUT \
    -H "X-Atlas-Token: $ATLAS_TOKEN"