openapi: 3.1.0
info:
  title: Vagrant Cloud Boxes 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: Boxes
  description: Endpoints for creating, reading, updating, and deleting Vagrant boxes in the Vagrant Cloud registry.
paths:
  /boxes:
    post:
      operationId: createBox
      summary: Create a box
      description: Creates a new Vagrant box under the authenticated user or specified organization. Requires authentication with a valid access token.
      tags:
      - Boxes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBoxRequest'
      responses:
        '200':
          description: Box created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Box'
        '401':
          description: Authentication required
        '422':
          description: Validation error
  /box/{username}/{name}:
    get:
      operationId: readBox
      summary: Read a box
      description: Retrieves detailed information about a specific Vagrant box, including its versions, providers, and metadata. Public boxes do not require authentication.
      tags:
      - Boxes
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/boxName'
      responses:
        '200':
          description: Box details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Box'
        '404':
          description: Box not found
    put:
      operationId: updateBox
      summary: Update a box
      description: Updates the metadata of an existing Vagrant box, such as its description, short description, or privacy settings.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/boxName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBoxRequest'
      responses:
        '200':
          description: Box updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Box'
        '401':
          description: Authentication required
        '404':
          description: Box not found
    delete:
      operationId: deleteBox
      summary: Delete a box
      description: Permanently deletes a Vagrant box and all of its versions and providers. This action cannot be undone.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/boxName'
      responses:
        '200':
          description: Box deleted successfully
        '401':
          description: Authentication required
        '404':
          description: Box not found
  /vagrant/2023-01-01/registry/{registry}/boxes:
    get:
      operationId: listBoxes
      summary: List boxes
      description: Lists all Vagrant boxes within a specific registry. Supports pagination for registries with many boxes.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/registryName'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: List of boxes returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBoxesResponse'
        '404':
          description: Registry not found
    post:
      operationId: createBox
      summary: Create a box
      description: Creates a new Vagrant box within a registry. The box name must be unique within the registry and should only be set at creation time.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/registryName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBoxRequest_2'
      responses:
        '200':
          description: Box created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoxResponse'
        '401':
          description: Authentication required
        '404':
          description: Registry not found
        '409':
          description: Box name already exists in the registry
  /vagrant/2023-01-01/registry/{registry}/box/{box}:
    get:
      operationId: readBox
      summary: Read a box
      description: Retrieves detailed information about a specific Vagrant box within a registry.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/registryName'
      - $ref: '#/components/parameters/boxName_2'
      responses:
        '200':
          description: Box details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoxResponse'
        '404':
          description: Box not found
    put:
      operationId: updateBox
      summary: Update a box
      description: Updates the metadata of an existing Vagrant box within a registry, such as its descriptions.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/registryName'
      - $ref: '#/components/parameters/boxName_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBoxRequest_2'
      responses:
        '200':
          description: Box updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoxResponse'
        '401':
          description: Authentication required
        '404':
          description: Box not found
    delete:
      operationId: deleteBox
      summary: Delete a box
      description: Permanently deletes a box and all of its versions and providers from the registry. This action cannot be undone.
      tags:
      - Boxes
      parameters:
      - $ref: '#/components/parameters/registryName'
      - $ref: '#/components/parameters/boxName_2'
      responses:
        '200':
          description: Box deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
        '401':
          description: Authentication required
        '404':
          description: Box not found
components:
  parameters:
    boxName:
      name: name
      in: path
      required: true
      description: The name of the Vagrant box.
      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:
    ListBoxesResponse:
      type: object
      description: Response containing a list of boxes and pagination information.
      properties:
        boxes:
          type: array
          description: List of boxes in the registry.
          items:
            $ref: '#/components/schemas/Box_2'
        pagination:
          $ref: '#/components/schemas/Pagination'
    OperationResponse:
      type: object
      description: Response containing an operation object for asynchronous actions.
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
    Box_2:
      type: object
      description: A Vagrant box within an HCP registry. The box name combined with the registry name forms the full box tag.
      properties:
        name:
          type: string
          description: The name segment of the box, unique within the registry.
        registry:
          type: string
          description: The name of the registry this box belongs to.
        short_description:
          type: string
          description: A brief description of the box limited to 100 characters.
          maxLength: 100
        description:
          type: string
          description: The full description of the box.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the box was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the box was last updated.
        downloads:
          type: integer
          description: The total number of downloads for this box.
    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.
    BoxResponse:
      type: object
      description: Response containing a box object.
      properties:
        box:
          $ref: '#/components/schemas/Box_2'
    UpdateBoxRequest:
      type: object
      description: Request body for updating an existing Vagrant box.
      properties:
        box:
          type: object
          properties:
            short_description:
              type: string
              description: A brief description of the box, limited to 100 characters.
              maxLength: 100
            description:
              type: string
              description: The full description of the box in Markdown format.
            is_private:
              type: boolean
              description: Whether the box should be private.
    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'
    UpdateBoxRequest_2:
      type: object
      description: Request body for updating a box in a registry.
      properties:
        short_description:
          type: string
          description: An updated brief description limited to 100 characters.
          maxLength: 100
        description:
          type: string
          description: An updated full description.
    CreateBoxRequest_2:
      type: object
      description: Request body for creating a new box in a registry.
      required:
      - name
      properties:
        name:
          type: string
          description: The name segment of the box, unique within the registry.
        short_description:
          type: string
          description: A brief description limited to 100 characters.
          maxLength: 100
        description:
          type: string
          description: The full description of the box.
    Box:
      type: object
      description: A Vagrant box is a package format for Vagrant environments that includes the base image and metadata for one or more providers.
      properties:
        tag:
          type: string
          description: The full tag of the box in username/name format.
        username:
          type: string
          description: The username or organization that owns the box.
        name:
          type: string
          description: The name of the box.
        private:
          type: boolean
          description: Whether the box is private and requires authentication to access.
        downloads:
          type: integer
          description: The total number of downloads for this box across all versions.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the box was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the box was last updated.
        short_description:
          type: string
          description: A brief description of the box, limited to 100 characters.
          maxLength: 100
        description_html:
          type: string
          description: The full description of the box rendered as HTML.
        description_markdown:
          type: string
          description: The full description of the box in Markdown format.
        versions:
          type: array
          description: List of versions available for this box.
          items:
            $ref: '#/components/schemas/Version'
        current_version:
          description: The current released version of this box.
          $ref: '#/components/schemas/Version'
    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.
    CreateBoxRequest:
      type: object
      description: Request body for creating a new Vagrant box.
      required:
      - box
      properties:
        box:
          type: object
          required:
          - username
          - name
          properties:
            username:
              type: string
              description: The username or organization to create the box under.
            name:
              type: string
              description: The name of the box.
            short_description:
              type: string
              description: A brief description of the box, limited to 100 characters.
              maxLength: 100
            description:
              type: string
              description: The full description of the box in Markdown format.
            is_private:
              type: boolean
              description: Whether the box should be private.
              default: false
  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