Endpoints for managing versions of a Vagrant box, including creating new versions and releasing them for consumption.
openapi: 3.1.0
info:
title: Vagrant Cloud Boxes Versions 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: Versions
description: Endpoints for managing versions of a Vagrant box, including creating new versions and releasing them for consumption.
paths:
/box/{username}/{name}/versions:
post:
operationId: createVersion
summary: Create a version
description: Creates a new version for an existing Vagrant box. The version string must follow semantic versioning. New versions are created in an unreleased state and must be explicitly released after uploading provider files.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVersionRequest'
responses:
'200':
description: Version created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'401':
description: Authentication required
'404':
description: Box not found
'422':
description: Validation error
/box/{username}/{name}/version/{version}:
get:
operationId: readVersion
summary: Read a version
description: Retrieves detailed information about a specific version of a Vagrant box, including its providers and release status.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
responses:
'200':
description: Version details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'404':
description: Version not found
put:
operationId: updateVersion
summary: Update a version
description: Updates the metadata of an existing version, such as its description.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateVersionRequest'
responses:
'200':
description: Version updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'401':
description: Authentication required
'404':
description: Version not found
delete:
operationId: deleteVersion
summary: Delete a version
description: Permanently deletes a version and all of its providers. This action cannot be undone.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
responses:
'200':
description: Version deleted successfully
'401':
description: Authentication required
'404':
description: Version not found
/box/{username}/{name}/version/{version}/release:
put:
operationId: releaseVersion
summary: Release a version
description: Releases a version, making it available for consumption by Vagrant users. A version must have at least one provider with an uploaded box file before it can be released.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
responses:
'200':
description: Version released successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'401':
description: Authentication required
'404':
description: Version not found
'422':
description: Version cannot be released
/box/{username}/{name}/version/{version}/revoke:
put:
operationId: revokeVersion
summary: Revoke a version
description: Revokes a previously released version, making it unavailable for download by Vagrant users.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/username'
- $ref: '#/components/parameters/boxName'
- $ref: '#/components/parameters/versionNumber'
responses:
'200':
description: Version revoked successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
'401':
description: Authentication required
'404':
description: Version not found
/vagrant/2023-01-01/registry/{registry}/box/{box}/versions:
get:
operationId: listVersions
summary: List versions
description: Lists all versions of a specific box within a registry. Supports pagination for boxes with many versions.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: List of versions returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListVersionsResponse'
'404':
description: Box not found
post:
operationId: createVersion
summary: Create a version
description: Creates a new version for a box. The version string must be unique within the box and should follow semantic versioning.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVersionRequest_2'
responses:
'200':
description: Version created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VersionResponse'
'401':
description: Authentication required
'404':
description: Box not found
'409':
description: Version already exists
/vagrant/2023-01-01/registry/{registry}/box/{box}/version/{version}:
get:
operationId: readVersion
summary: Read a version
description: Retrieves detailed information about a specific version of a box within a registry.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
responses:
'200':
description: Version details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VersionResponse'
'404':
description: Version not found
delete:
operationId: deleteVersion
summary: Delete a version
description: Permanently deletes a version and all of its providers from the box. This action cannot be undone.
tags:
- Versions
parameters:
- $ref: '#/components/parameters/registryName'
- $ref: '#/components/parameters/boxName_2'
- $ref: '#/components/parameters/versionName'
responses:
'200':
description: Version deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OperationResponse'
'401':
description: Authentication required
'404':
description: Version not found
components:
parameters:
boxName:
name: name
in: path
required: true
description: The name of the Vagrant box.
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
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
pageSize:
name: page_size
in: query
description: The maximum number of results to return per page.
schema:
type: integer
minimum: 1
boxName_2:
name: box
in: path
required: true
description: The name segment of the box which is unique within the registry.
schema:
type: string
pageToken:
name: page_token
in: query
description: The token for fetching the next page of results.
schema:
type: string
schemas:
VersionResponse:
type: object
description: Response containing a version object.
properties:
version:
$ref: '#/components/schemas/Version_2'
OperationResponse:
type: object
description: Response containing an operation object for asynchronous actions.
properties:
operation:
$ref: '#/components/schemas/Operation'
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.
Pagination:
type: object
description: Pagination information for list responses.
properties:
next_page_token:
type: string
description: The token to use for fetching the next page of results. Empty when there are no more results.
ListVersionsResponse:
type: object
description: Response containing a list of versions and pagination information.
properties:
versions:
type: array
description: List of versions for the box.
items:
$ref: '#/components/schemas/Version_2'
pagination:
$ref: '#/components/schemas/Pagination'
Version:
type: object
description: A version of a Vagrant box following semantic versioning. Versions must be released before they are available for download.
properties:
version:
type: string
description: The version number following semantic versioning.
status:
type: string
description: The release status of the version.
enum:
- unreleased
- active
- revoked
description_html:
type: string
description: The version description rendered as HTML.
description_markdown:
type: string
description: The version description in Markdown format.
created_at:
type: string
format: date-time
description: The timestamp when the version was created.
updated_at:
type: string
format: date-time
description: The timestamp when the version was last updated.
number:
type: string
description: The version number string.
downloads:
type: integer
description: The total number of downloads for this version.
providers:
type: array
description: List of providers available for this version.
items:
$ref: '#/components/schemas/Provider'
CreateVersionRequest:
type: object
description: Request body for creating a new version of a Vagrant box.
required:
- version
properties:
version:
type: object
required:
- version
properties:
version:
type: string
description: The version number following semantic versioning.
description:
type: string
description: The description of this version in Markdown format.
UpdateVersionRequest:
type: object
description: Request body for updating an existing version.
properties:
version:
type: object
properties:
version:
type: string
description: The updated version number.
description:
type: string
description: The updated description in Markdown format.
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.
Version_2:
type: object
description: A version of a Vagrant box. Versions support long-form descriptions and must have unique version strings within the box.
properties:
version:
type: string
description: The version string which must be unique within the box.
description:
type: string
description: The description of this version.
state:
type: string
description: The state of the version.
enum:
- UNRELEASED
- ACTIVE
- REVOKED
created_at:
type: string
format: date-time
description: The timestamp when the version was created.
updated_at:
type: string
format: date-time
description: The timestamp when the version was last updated.
CreateVersionRequest_2:
type: object
description: Request body for creating a new version of a box.
required:
- version
properties:
version:
type: string
description: The version string following semantic versioning.
description:
type: string
description: A description of this version.
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