Boxes API

Vagrant Boxes can be created and managed via the API. The box serves as the namespace for versions and providers.

Before creating versions with attached providers, you'll need to create a box.

Box Attributes

Attribute Description Required
name The name of the box, used to identify it. The name makes up the latter half of the `tag`. It has a maximum length of 36 characters and must contain only letters, numbers, dashes, underscores or periods. Yes
username The username to assign the box to. You must be a member of the organization and have the ability to create boxes. Defaults to the users username that is making the API request. Yes
short_description The short description is used on small box previews, in search results and other places where displaying markdown isn't functional. It has a maxium length of 120 characters. No
description Markdown text used as a full-length and in-depth description of the box. Markdown is parsed according to [GitHub Flavored Markdown]( There is no maximum length. No
is_private A boolean if the box should be private or not. Defaults to false. No


The following actions can be perfomed on this resource.

GET /api/v1/box/:username/:name
POST /api/v1/boxes
PUT /api/v1/box/:username/:name
DELETE /api/v1/box/:username/:name


Creating a box

Creates a box with the provided attributes.

$ curl \
    -X POST \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d box[name]='acmeinc/test'

Retrieving a box

Returns the JSON respresentation of the box.

$ curl \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Updating a box

Updates the attributes provided for the box.

$ curl \
    -X PUT \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d box[description]='updating the description'

Destroying a box

Deletes the box and all associated versions and providers permanently from Atlas.

$ curl \
    -X DELETE \
    -H "X-Atlas-Token: $ATLAS_TOKEN"