Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application.
Requests to Vagrant Cloud which include data attributes (POST or PUT/PATCH) should set the Content-Type header to "application/json", and include a valid JSON body with the request.
JSON responses may include an errors key, which will contain an array of error strings, as well as a success key.
For example:
{"errors":["Resource not found!"],"success":false}
{"errors":["Resource not found!"],"success":false}
You are trying to access a resource which is delinquent on billing.
Please contact the owner of the resource so that they can update their billing information.
You are attempting to use the system in a way which is not allowed.
There could be required request parameters that are missing, or one of the parameters is invalid.
Please check the response errors key, and double-check the examples below for any discrepancies.
The resource you are trying to access does not exist. This may also be returned if you attempt to access a private resource that you don't have authorization to view.
You are currently being rate-limited. Please decrease your frequency of usage, or contact us at support+vagrantcloud@hashicorp.com with a description of your use case so that we can consider creating an exception.
The server failed to respond to the request for an unknown reason.
Please contact support+vagrantcloud@hashicorp.com with a description of the problem so that we can investigate.
{"description":"Login from cURL","token":"qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs","token_hash":"7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c","created_at":"2017-10-18T19:16:24.956Z"}
{"description":"Login from cURL","token":"qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs","token_hash":"7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c","created_at":"2017-10-18T19:16:24.956Z"}
{"username":"myuser","avatar_url":"https://www.gravatar.com/avatar/130a640278870c3dada38b3d912ee022?s=460&d=mm","profile_html":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>\n","profile_markdown":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.","boxes":[]}
{"username":"myuser","avatar_url":"https://www.gravatar.com/avatar/130a640278870c3dada38b3d912ee022?s=460&d=mm","profile_html":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>\n","profile_markdown":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.","boxes":[]}
q - (Optional) The search query. Results will match the username, name, or short_description fields for a box. If omitted, the top boxes based on sort and order will be returned (defaults to "downloads desc").
provider - (Optional) Filter results to boxes supporting for a specific provider.
sort - (Optional, default: "downloads") The field to sort results on. Can be one of "downloads", "created", or "updated".
order - (Optional, default: "desc") The order to return the sorted field in. Can be "desc" os "asc".
limit - (Optional, default: 10) The number of results to return (max of 100).
{"boxes":[{"created_at":"2017-10-20T14:19:59.842Z","updated_at":"2017-10-20T15:23:53.363Z","tag":"myuser/test","name":"test","short_description":"My dev box","description_html":"<p>My development Vagrant box</p>\n","username":"myuser","description_markdown":"My development Vagrant box","private":true,"downloads":123,"current_version":{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}}]}
{"boxes":[{"created_at":"2017-10-20T14:19:59.842Z","updated_at":"2017-10-20T15:23:53.363Z","tag":"myuser/test","name":"test","short_description":"My dev box","description_html":"<p>My development Vagrant box</p>\n","username":"myuser","description_markdown":"My development Vagrant box","private":true,"downloads":123,"current_version":{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}}]}
{"created_at":"2017-10-20T14:19:59.842Z","updated_at":"2017-10-20T15:23:53.363Z","tag":"myuser/test","name":"test","short_description":"My dev box","description_html":"<p>My development Vagrant box</p>\n","username":"myuser","description_markdown":"My development Vagrant box","private":true,"downloads":123,"current_version":{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]},"versions":[{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}]}
{"created_at":"2017-10-20T14:19:59.842Z","updated_at":"2017-10-20T15:23:53.363Z","tag":"myuser/test","name":"test","short_description":"My dev box","description_html":"<p>My development Vagrant box</p>\n","username":"myuser","description_markdown":"My development Vagrant box","private":true,"downloads":123,"current_version":{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]},"versions":[{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}]}
{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}
{"version":"1.2.3","status":"active","description_html":"<p>A new version</p>\n","description_markdown":"A new version","created_at":"2017-10-20T15:23:17.184Z","updated_at":"2017-10-20T15:23:53.355Z","number":"1.2.3","release_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release","revoke_url":"https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke","providers":[{"name":"virtualbox","hosted":false,"hosted_token":null,"original_url":"https://example.com/virtualbox-1.2.3.box","created_at":"2017-10-20T15:23:35.718Z","updated_at":"2017-10-20T15:23:35.718Z","download_url":"https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box"}]}
url - A valid URL to download this provider. If omitted, you must upload the Vagrant box image for this provider to Vagrant Cloud before the provider can be used.
checksum - Computed checksum of the box assets. When set, Vagrant will compute the checksum of the downloaded box asset and validate it matches this value.
checksum_type - Type of checksum used. Currently supported values: md5, sha1, sha256, sha384, and sha512
url - A valid URL to download this provider. If omitted, you must upload the Vagrant box image for this provider to Vagrant Cloud before the provider can be used.
GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload
Prepares the provider for upload, and returns a JSON blob containing an upload_path.
The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL.
GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload/direct
Prepares the provider for upload. This version of the upload API allows uploading the box asset directly to the backend storage. It requires
a two step process for uploading the box assets. First uploading the asset to storage and then finalizing the upload within Vagrant Cloud
via a provided callback.
The request returns a JSON blob containing two fields:
callback - Vagrant Cloud callback URL to finalize upload
The box asset is uploaded directly to the URL provided by the upload_path via a PUT request. Once complete, a PUT request to the URL
provided in the callback field (complete with authentication header) finalizes the upload.
The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL.
