Endpoints for managing providers within a box version, including creating providers and uploading box files.
openapi: 3.1.0
info:
title: Vagrant Cloud Boxes Providers API
description: The Vagrant Cloud API v2 enables developers to programmatically interact with the Vagrant Cloud platform for managing Vagrant boxes, versions, and providers. It supports creating and updating boxes, publishing new versions, uploading provider binaries, and searching the public box catalog. The API uses token-based authentication and is designed for automating box lifecycle management and integrating Vagrant Cloud into CI/CD pipelines.
version: '2'
contact:
name: HashiCorp Support
url: https://support.hashicorp.com
termsOfService: https://www.hashicorp.com/terms-of-service
servers:
- url: https://app.vagrantup.com/api/v2
description: Vagrant Cloud Production Server
security:
- bearerAuth: []
tags:
- name: Providers
description: Endpoints for managing providers within a box version, including creating providers and uploading box files.
paths:
/box/{username}/{name}/version/{version}/providers:
post:
operationId: createProvider
summary: Create a provider
description: Creates a new provider for a specific version of a Vagrant box. A provider represents a specific virtualization platform (such as virtualbox, vmware_desktop, or docker) for which a box file is available.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProviderRequest'
responses:
'200':
description: Provider created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'401':
description: Authentication required
'404':
description: Version not found
'422':
description: Validation error
/box/{username}/{name}/version/{version}/provider/{provider}:
get:
operationId: readProvider
summary: Read a provider
description: Retrieves detailed information about a specific provider within a version of a Vagrant box.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/providerName'
responses:
'200':
description: Provider details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'404':
description: Provider not found
put:
operationId: updateProvider
summary: Update a provider
description: Updates the metadata of an existing provider, such as its URL or checksum information.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/providerName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProviderRequest'
responses:
'200':
description: Provider updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'401':
description: Authentication required
'404':
description: Provider not found
delete:
operationId: deleteProvider
summary: Delete a provider
description: Permanently deletes a provider from a version. This action cannot be undone.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/providerName'
responses:
'200':
description: Provider deleted successfully
'401':
description: Authentication required
'404':
description: Provider not found
/box/{username}/{name}/version/{version}/provider/{provider}/upload:
get:
operationId: getUploadUrl
summary: Get upload URL
description: Returns a pre-signed upload URL for uploading a box file to the specified provider. The client should use the returned URL to upload the box file via an HTTP PUT request.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/providerName'
responses:
'200':
description: Upload URL returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UploadPath'
'401':
description: Authentication required
'404':
description: Provider not found
/box/{username}/{name}/version/{version}/provider/{provider}/upload/direct:
get:
operationId: getDirectUploadUrl
summary: Get direct upload URL
description: Returns a pre-signed URL for directly uploading a box file to cloud storage, bypassing the Vagrant Cloud server. This is recommended for large box files to improve upload performance.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
- $ref: '#/components/parameters/providerName'
responses:
'200':
description: Direct upload URL returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DirectUploadPath'
'401':
description: Authentication required
'404':
description: Provider not found
/vagrant/2023-01-01/registry/{registry}/box/{box}/version/{version}/providers:
get:
operationId: listProviders
summary: List providers
description: Lists all providers for a specific version of a box within a registry.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
responses:
'200':
description: List of providers returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListProvidersResponse'
'404':
description: Version not found
post:
operationId: createProvider
summary: Create a provider
description: Creates a new provider for a specific version of a box. A provider represents a virtualization platform build of the box.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProviderRequest_2'
responses:
'200':
description: Provider created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderResponse'
'401':
description: Authentication required
'404':
description: Version not found
'409':
description: Provider already exists for this version
/vagrant/2023-01-01/registry/{registry}/box/{box}/version/{version}/provider/{provider}:
get:
operationId: readProvider
summary: Read a provider
description: Retrieves detailed information about a specific provider within a version of a box.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
- $ref: '#/components/parameters/providerName_2'
responses:
'200':
description: Provider details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderResponse'
'404':
description: Provider not found
delete:
operationId: deleteProvider
summary: Delete a provider
description: Permanently deletes a provider from a version. This action cannot be undone.
tags:
- Providers
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
- $ref: '#/components/parameters/providerName_2'
responses:
'200':
description: Provider deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResponse'
'401':
description: Authentication required
'404':
description: Provider not found
components:
parameters:
boxName:
name: name
in: path
required: true
description: The name of the Vagrant box.
schema:
type: string
providerName:
name: provider
in: path
required: true
description: The name of the provider such as virtualbox, vmware_desktop, or docker.
schema:
type: string
versionName:
name: version
in: path
required: true
description: The version string which must be unique within the box.
schema:
type: string
versionNumber:
name: version
in: path
required: true
description: The version number of the box following semantic versioning.
schema:
type: string
providerName_2:
name: provider
in: path
required: true
description: The name of the provider such as virtualbox or vmware_desktop.
schema:
type: string
username:
name: username
in: path
required: true
description: The username or organization name that owns the box.
schema:
type: string
registryName:
name: registry
in: path
required: true
description: The globally unique name of the Vagrant box registry such as hashicorp in hashicorp/vagrant.
schema:
type: string
boxName_2:
name: box
in: path
required: true
description: The name segment of the box which is unique within the registry.
schema:
type: string
schemas:
UpdateProviderRequest:
type: object
description: Request body for updating an existing provider.
properties:
provider:
type: object
properties:
name:
type: string
description: The updated name of the provider.
url:
type: string
format: uri
description: The updated URL of an externally hosted box file.
checksum_type:
type: string
description: The updated checksum type.
checksum:
type: string
description: The updated checksum value.
architecture:
type: string
description: The updated CPU architecture.
Provider_2:
type: object
description: A provider describes a specific virtualization platform build of a box version, with its list of architectures and box data.
properties:
name:
type: string
description: The name of the provider such as virtualbox or vmware_desktop.
url:
type: string
format: uri
description: The URL of the externally hosted box file.
checksum:
type: string
description: The checksum value for the box file.
checksum_type:
type: string
description: The type of checksum used.
enum:
- MD5
- SHA1
- SHA256
- SHA384
- SHA512
architecture:
type: string
description: The CPU architecture the box supports such as amd64 or arm64.
created_at:
type: string
format: date-time
description: The timestamp when the provider was created.
updated_at:
type: string
format: date-time
description: The timestamp when the provider was last updated.
OperationResponse:
type: object
description: Response containing an operation object for asynchronous actions.
properties:
operation:
$ref: '#/components/schemas/Operation'
CreateProviderRequest_2:
type: object
description: Request body for creating a new provider for a version.
required:
- name
properties:
name:
type: string
description: The name of the provider such as virtualbox or vmware_desktop.
url:
type: string
format: uri
description: The URL of an externally hosted box file.
checksum:
type: string
description: The checksum value for the box file.
checksum_type:
type: string
description: The type of checksum.
enum:
- MD5
- SHA1
- SHA256
- SHA384
- SHA512
architecture:
type: string
description: The CPU architecture such as amd64 or arm64.
Operation:
type: object
description: An operation returned by asynchronous API calls. The operation ID is unique within the region the operation is running in.
properties:
id:
type: string
description: The unique identifier of the operation within the region.
state:
type: string
description: The current state of the operation.
enum:
- PENDING
- RUNNING
- DONE
error:
type: object
description: Error details if the operation failed.
properties:
code:
type: integer
description: The error code.
message:
type: string
description: The error message.
ListProvidersResponse:
type: object
description: Response containing a list of providers.
properties:
providers:
type: array
description: List of providers for the version.
items:
$ref: '#/components/schemas/Provider_2'
DirectUploadPath:
type: object
description: Contains the direct upload URL for uploading a box file directly to cloud storage.
properties:
upload_path:
type: string
format: uri
description: The pre-signed URL to upload the box file directly to cloud storage via HTTP PUT.
callback:
type: string
format: uri
description: The callback URL to notify Vagrant Cloud after the upload completes.
token:
type: string
description: The upload token for this upload session.
UploadPath:
type: object
description: Contains the upload URL for uploading a box file to Vagrant Cloud.
properties:
upload_path:
type: string
format: uri
description: The pre-signed URL to upload the box file via HTTP PUT.
token:
type: string
description: The upload token for this upload session.
Provider:
type: object
description: A provider represents a specific virtualization platform for which a box file is available within a version.
properties:
name:
type: string
description: The name of the provider such as virtualbox or vmware_desktop.
hosted:
type: boolean
description: Whether the box file is hosted on Vagrant Cloud.
hosted_token:
type: string
description: The token used for hosted box file downloads.
original_url:
type: string
format: uri
description: The original URL of the box file if externally hosted.
download_url:
type: string
format: uri
description: The URL to download the box file.
created_at:
type: string
format: date-time
description: The timestamp when the provider was created.
updated_at:
type: string
format: date-time
description: The timestamp when the provider was last updated.
checksum_type:
type: string
description: The type of checksum used for the box file.
enum:
- md5
- sha1
- sha256
- sha384
- sha512
checksum:
type: string
description: The checksum value for the box file.
architecture:
type: string
description: The CPU architecture the box supports such as amd64 or arm64.
default_architecture:
type: boolean
description: Whether this is the default architecture for the provider.
ProviderResponse:
type: object
description: Response containing a provider object.
properties:
provider:
$ref: '#/components/schemas/Provider_2'
CreateProviderRequest:
type: object
description: Request body for creating a new provider for a version.
required:
- provider
properties:
provider:
type: object
required:
- name
properties:
name:
type: string
description: The name of the provider such as virtualbox or vmware_desktop.
url:
type: string
format: uri
description: The URL of an externally hosted box file. If omitted, the box file must be uploaded to Vagrant Cloud.
checksum_type:
type: string
description: The type of checksum for the box file.
enum:
- md5
- sha1
- sha256
- sha384
- sha512
checksum:
type: string
description: The checksum value for the box file.
architecture:
type: string
description: The CPU architecture the box supports.
default_architecture:
type: boolean
description: Whether this is the default architecture for the provider.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Vagrant Cloud API token passed as a Bearer token in the Authorization header.
externalDocs:
description: Vagrant Cloud API v2 Documentation
url: https://developer.hashicorp.com/vagrant/vagrant-cloud/api/v2