openapi: 3.1.0
info:
  title: Vagrant Cloud Boxes Search 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: Search
  description: Endpoints for searching the public Vagrant box catalog by query, provider, and other filters.
paths:
  /search:
    get:
      operationId: searchBoxes
      summary: Search boxes
      description: Searches the public Vagrant box catalog. The search query matches against the username, name, or short_description fields. If the query is omitted, the top boxes based on sort and order are returned.
      tags:
      - Search
      security: []
      parameters:
      - $ref: '#/components/parameters/searchQuery'
      - $ref: '#/components/parameters/searchProvider'
      - $ref: '#/components/parameters/searchSort'
      - $ref: '#/components/parameters/searchOrder'
      - $ref: '#/components/parameters/searchLimit'
      - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
components:
  parameters:
    searchQuery:
      name: q
      in: query
      description: Search query that matches against the username, name, or short_description fields.
      schema:
        type: string
    searchLimit:
      name: limit
      in: query
      description: The number of results to return per page, with a maximum of 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    searchSort:
      name: sort
      in: query
      description: The field to sort results on.
      schema:
        type: string
        enum:
        - downloads
        - created
        - updated
        default: downloads
    searchProvider:
      name: provider
      in: query
      description: Filter results to boxes supporting a specific provider such as virtualbox or vmware_desktop.
      schema:
        type: string
    searchPage:
      name: page
      in: query
      description: The page number to return for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    searchOrder:
      name: order
      in: query
      description: The order to return the sorted field in.
      schema:
        type: string
        enum:
        - desc
        - asc
        default: desc
  schemas:
    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:
      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'
    SearchResults:
      type: object
      description: Container for search results returned from the box catalog.
      properties:
        boxes:
          type: array
          description: List of boxes matching the search criteria.
          items:
            $ref: '#/components/schemas/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'
  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