Box Providers API

Providers contain the pointers to the box files, be it a hosted or self-hosted box. Box versions can have many providers, each which represents a Vagrant compatible provider, either from Vagrant Core as a 3rd party plugin.

Hosted Boxes

The provider API is used to host boxes. To create a hosted box, simply omit the URL parameter. You will then be able to use the upload endpoint to upload a box to us.

The upload endpoint responds with a 302 FOUND HTTP response, redirecting you to the final location for upload. Your HTTP client will need to be configured to follow redirects for this to work.

Box Provider Attributes

Attribute Description Required
name The name of the provider. Vagrant will use this to determine compatible boxes on the client. Common providers include virtualbox, vmware_desktop, aws, digitalocean, docker, google, hyperv, rackspace, parallels, and veertu Yes
url An HTTP URL to the box file. This must be accessible at this URL from the machine where you expect a user to download the box by using Vagrant. If ommitted, we assume you wish to host the provider on Atlas. No

Actions

The following actions can be perfomed on this resource.

Show
GET /api/v1/box/:username/:name/version/:number/provider/:name
Create
POST /api/v1/box/:username/:name/version/:number/providers
Update
PUT /api/v1/box/:username/:name/version/:number/provider/:name
Delete
DELETE /api/v1/box/:username/:name/version/:number/provider/:name
Upload
GET /api/v1/box/:username/:name/version/:number/provider/:name/upload
Download
GET /:username/:name/version/:number/provider/:name.box

Examples

Create a provider

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

Retrieve a provider

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

Update a provider

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

Destroy a provider

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

Upload a .box file for a provider

Uploading a box for a provider is a two-step process. First, you must make a GET request to the /upload endpoint for the provider:

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

This response body will be JSON of the form:

{
  "upload_path": "https://binstore.hashicorp.com/630e42d9-2364-2412-4121-18266770468e",
  "token": "630e42d9-2364-2412-4121-18266770468e"
}

The value in the upload_path key is a uniquely generated, time-sensitive URL. The second step in the upload process is to PUT (upload) your raw box fie to the upload_path:

$ curl -X PUT --upload-file /path/to/my.box https://binstore.hashicorp.com/630e42d9-2364-2412-4121-18266770468e
Download a .box for a provider
$ curl https://atlas.hashicorp.com/acmeinc/boxes/test/versions/1.0/providers/virtualbox.box \
    -L \
    -X GET \
    -H "X-Atlas-Token: $ATLAS_TOKEN"