beckermj/vaguerent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
vaguerent/website/source/docs/vagrant-cloud/api.html.md
Justin Campbell 9c00219903 website: Vagrant Cloud API docs
2017-10-20 16:32:03 -04:00

36 KiB
Raw Blame History

layout page_title sidebar_current
docs Vagrant Cloud API vagrant-cloud-api

Vagrant Cloud API

Using the API

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.

Authentication

Some API endpoints require authentication to create new resources, update or delete existing resources, or to read a private resource.

Clients can authenticate using an authentication token. The token can be passed to Vagrant Cloud one of two ways:

  1. (Preferred) Set the X-Atlas-Token header to the value of the authentication token.
  2. Pass the authentication token as an access_token URL parameter.

Examples below will set the header, but feel free to use whichever method is easier for your implementation.

-> The header name X-Atlas-Token is an artifact of Vagrant Cloud's previous project name, "Atlas". -> This header will be updated in the near future, but X-Atlas-Token will continue to be supported for now to ensure backwards-compatibility.

Request and Response Format

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
}

Response Codes

Vagrant Cloud may response with the following response codes, depending on the status of the request and context:

Success

200 OK
201 Created

Client Errors

401 Unauthorized

You do not have authorization to access the requested resource.

402 Payment Required

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.

403 Forbidden

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.

404 Not Found

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.

422 Unprocessable Entity
429 Too Many Requests

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.

Server Errors

500 Internal Server Error

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.

503 Service Unavailable

Vagrant Cloud is temporarily in maintenance mode. Please check the HashiCorp Status Site for more information.

Creating a usable box from scratch

-> This assumes that you have a valid Vagrant Cloud authentication token. You can create one via the API, or create one on the Vagrant Cloud website.

In order to create a usable box on Vagrant Cloud, perform the following steps:

  1. Create a new box
  2. Create a new version
  3. Create a new provider
  4. Upload a box image for that provider
  5. Release the version

Example Requests

  • cURL
  • Ruby
```shell # Create a new box curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/boxes \ --data '{ "box": { "username": "myuser", "name": "test" } }' 
# Create a new version
curl \
  --header "Content-Type: application/json" \
  --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \
  https://app.vagrantup.com/api/v1/box/myuser/test/versions \
  --data '{ "version": { "version": "1.2.3" } }'

# Create a new provider
curl \
  --header "Content-Type: application/json" \
  --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \
  https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \
  --data '{ "provider": { "name": "virtualbox" } }'

# Prepare the provider for upload/get an upload URL
response=$(curl \
  --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \
  https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload)

# Extract the upload URL from the response (requires the jq command)
upload_path=$(echo "$response" | jq .upload_path)

# Perform the upload
curl $upload_path --request PUT --upload-file virtualbox-1.2.3.box

# Release the version
curl \
  --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \
  https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \
  --request PUT
```

```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

# Create a new box
api.post "/api/v1/boxes",
  json: { box: { username: "myuser", name: "test" } }

# Create a new version
api.post "/api/v1/box/myuser/test/versions",
  json: { version: { version: "1.2.3" } }

# Create a new provider
api.post "/api/v1/box/myuser/test/version/1.2.3/providers",
  json: { provider: { name: "virtualbox" } }

# Prepare the provider for upload
response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload")

# Extract the upload URL
upload_path = response.parse['upload_path']

# Upload the box image
HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box")
```

Authentication Tokens

Create a token

POST /api/v1/authenticate

Creates a new token for the given user.

Arguments

  • token
    • desription (Optional) - A description of the token.
  • user
    • login - Username or email address of the user authenticating.
    • password - The user's password.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ https://app.vagrantup.com/api/v1/authenticate \ --data ' { "token": { "description": "Login from cURL" }, "user": { "login": "myuser", "password": "secretpassword" } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json"
)

response = api.post("/api/v1/authenticate", json: {
  token: { description: "Login from Ruby" },
  user: { login: "myuser", password: "secretpassword" }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

{
  "description": "Login from cURL",
  "token": "qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs",
  "token_hash": "7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c",
  "created_at": "2017-10-18T19:16:24.956Z"
}

Validate a token

GET /api/v1/authenticate

Responds 200 OK if the authentication request was successful, otherwise responds 401 Unauthorized.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/authenticate ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.get("/api/v1/authenticate")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Boxes

Read a box

GET /api/v1/box/:username/:name

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.get("/api/v1/box/myuser/test")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

{
  "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,
  "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"
        }
      ]
    }
  ]
}

Create a box

POST /api/v1/boxes

Arguments

  • box
    • username - The username of the organization that will own this box.
    • name - The name of the box.
    • short_description - A short summary of the box.
    • description - A longer description of the box. Can be formatted with Markdown.
    • is_private (Optional, default: true) - Whether or not this box is private.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/boxes \ --data ' { "box": { "username": "myuser", "name": "test", "short_description": "My dev box", "description": "My development Vagrant box", "is_private": true } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.post("/api/v1/boxes", json: {
  box: {
    username: "myuser",
    name: "test",
    short_description: "My dev box",
    description: "My development Vagrant box",
    is_private: true
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a box.

Update a box

PUT /api/v1/box/:username/:name

Arguments

  • box
    • name - The name of the box.
    • short_description - A short summary of the box.
    • description - A longer description of the box. Can be formatted with Markdown.
    • is_private (Optional, default: true) - Whether or not this box is private.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test \ --request PUT \ --data ' { "box": { "name": "test", "short_description": "My dev box", "description": "My development Vagrant box", "is_private": true } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.put("/api/v1/box/myuser/test", json: {
  box: {
    name: "test",
    short_description: "My dev box",
    description: "My development Vagrant box",
    is_private: true
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Delete a box

DELETE /api/v1/box/:username/:name

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ --request DELETE \ https://app.vagrantup.com/api/v1/box/myuser/test ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.delete("/api/v1/box/myuser/test")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a box.

Versions

Read a version

GET /api/v1/box/:username/:name/version/:version

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.get("/api/v1/box/myuser/test/version/1.2.3")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

{
  "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"
    }
  ]
}

Create a version

POST /api/v1/box/:username/:name/versions

-> New versions start as unreleased. You must create a valid provider before releasing a new version.

Arguments

  • version
    • versions - The version number of this version.
    • description - A description for this version. Can be formatted with Markdown.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/versions \ --data ' { "version": { "version": "1.2.3", "description": "A new version" } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.post("/api/v1/box/myuser/test/versions", json: {
  version: {
    version: "1.2.3",
    description: "A new version"
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a version.

Update a version

PUT /api/v1/box/:username/:name/version/1.2.3

Arguments

  • version
    • versions - The version number of this version.
    • description - A description for this version. Can be formatted with Markdown.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 \ --request PUT \ --data ' { "version": { "version": "1.2.3", "description": "A new version" } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.put("/api/v1/box/myuser/test/version/1.2.3", json: {
  version: {
    name: "1.2.3",
    description: "A new version"
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a version.

Delete a version

DELETE /api/v1/box/:username/:name/version/:version

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ --request DELETE \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.delete("/api/v1/box/myuser/test/version/1.2.3")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a version.

Release a version

PUT /api/v1/box/:username/:name/version/1.2.3/release

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \ --request PUT ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.put("/api/v1/box/myuser/test/version/1.2.3/release")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a version.

Revoke a version

PUT /api/v1/box/:username/:name/version/1.2.3/revoke

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke \ --request PUT ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.put("/api/v1/box/myuser/test/version/1.2.3/revoke")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a version.

Providers

Read a provider

GET /api/v1/box/:username/:name/version/:version/provider/:provider

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

{
  "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"
}

Create a provider

POST /api/v1/box/:username/:name/version/:version/providers

Arguments

  • provider
    • name - The name of the provider.
    • 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.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ --data ' { "provider": { "name": "virtualbox", "url": "https://example.com/virtualbox-1.2.3.box" } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.post("/api/v1/box/myuser/test/version/1.2.3/providers", json: {
  provider: {
    name: "virtualbox",
    url: "https://example.com/virtualbox-1.2.3.box"
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a provider.

Update a provider

PUT /api/v1/box/:username/:name/version/:version/provider/:provider

Arguments

  • provider
    • name - The name of the provider.
    • 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.

Example Request

  • cURL
  • Ruby
```shell curl \ --header "Content-Type: application/json" \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/virtualbox \ --request PUT \ --data ' { "provider": { "name": "virtualbox", "url": "https://example.com/virtualbox-1.2.3.box" } } ' ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "Content-Type" => "application/json",
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.put("/api/v1/box/myuser/test/version/1.2.3/virtualbox", json: {
  provider: {
    name: "virtualbox",
    url: "https://example.com/virtualbox-1.2.3.box"
  }
})

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a provider.

Delete a provider

DELETE /api/v1/box/:username/:name/version/:version/provider/:provider

Example Request

  • cURL
  • Ruby
```shell curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ --request DELETE \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox ``` 
```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.delete("/api/v1/box/myuser/test/verison/1.2.3/provider/virtualbox")

if response.status.success?
  # Success, the response attributes are available here.
  p response.parse
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

Response body is identical to Reading a provider.

Upload a provider

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.

Example Request

  • cURL
  • Ruby
```shell response=$(curl \ --header "X-Atlas-Token: $VAGRANT_CLOUD_TOKEN" \ https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/virtualbox/upload) 
# Requires the jq command
upload_path=$(echo "$response" | jq .upload_path)

curl \
 $upload_path \
  --request PUT \
  --upload-file virtualbox-1.2.3.box
```

```ruby
# gem install http, or add `gem "http"` to your Gemfile
require "http"

api = HTTP.persistent("https://app.vagrantup.com").headers(
  "X-Atlas-Token" => ENV['VAGRANT_CLOUD_TOKEN']
)

response = api.get("/api/v1/box/myuser/test/version/1.2.3/virtualbox/upload")

if response.status.success?
  # Success, you can now upload the box image to the returned URL
  upload_path = response.parse['upload_path']
  HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box")
else
  # Error, inspect the `errors` key for more information.
  p response.code, response.body
end
```

Example Response

{
  "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e"
}