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