Vagrant Registries API

openapi: 3.2.0
info:
  title: HCP Vagrant Box Registry Registries API
  description: The HCP Vagrant Box Registry API provides REST endpoints for managing Vagrant box registries and boxes on the HashiCorp Cloud Platform. It supports creating and managing registries, listing and deleting boxes, and handling box versions and providers. The API uses HCP service principal credentials for authentication and is the successor to the legacy Vagrant Cloud service, offering tighter integration with the broader HashiCorp Cloud Platform ecosystem.
  version: '2023-01-01'
  contact:
    name: HashiCorp Support
    url: https://support.hashicorp.com
  termsOfService: https://www.hashicorp.com/terms-of-service
servers:
- url: https://api.cloud.hashicorp.com
  description: HCP Production Server
security:
- bearerAuth: []
tags:
- name: Registries
  description: Endpoints for managing Vagrant box registries. A registry is a namespace that holds boxes and forms the first segment of a box tag such as hashicorp in hashicorp/vagrant.
paths:
  /vagrant/2023-01-01/registry:
    post:
      operationId: createRegistry
      summary: Create a registry
      description: Creates a new Vagrant box registry on the HashiCorp Cloud Platform. The registry name must be globally unique and will form the first segment of all box tags within the registry.
      tags:
      - Registries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegistryRequest'
      responses:
        '200':
          description: Registry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryResponse'
        '401':
          description: Authentication required
        '409':
          description: Registry name already exists
        '422':
          description: Validation error
  /vagrant/2023-01-01/registry/{registry}:
    get:
      operationId: readRegistry
      summary: Read a registry
      description: Retrieves detailed information about a specific Vagrant box registry on the HashiCorp Cloud Platform.
      tags:
      - Registries
      parameters:
      - $ref: '#/components/parameters/registryName'
      responses:
        '200':
          description: Registry details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryResponse'
        '404':
          description: Registry not found
    delete:
      operationId: deleteRegistry
      summary: Delete a registry
      description: Permanently deletes a Vagrant box registry and all of its boxes, versions, and providers. This action cannot be undone.
      tags:
      - Registries
      parameters:
      - $ref: '#/components/parameters/registryName'
      responses:
        '200':
          description: Registry deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
        '401':
          description: Authentication required
        '404':
          description: Registry not found
components:
  schemas:
    CreateRegistryRequest:
      type: object
      description: Request body for creating a new Vagrant box registry.
      required:
      - name
      properties:
        name:
          type: string
          description: The globally unique name for the registry.
        description:
          type: string
          description: A description of the registry.
    Registry:
      type: object
      description: A Vagrant box registry is a namespace on the HashiCorp Cloud Platform that holds boxes. The registry name forms the first segment of a box tag.
      properties:
        id:
          type: string
          description: The unique identifier of the registry.
        name:
          type: string
          description: The globally unique name of the registry.
        description:
          type: string
          description: The description of the registry.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the registry was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the registry was last updated.
    RegistryResponse:
      type: object
      description: Response containing a registry object.
      properties:
        registry:
          $ref: '#/components/schemas/Registry'
    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.
    OperationResponse:
      type: object
      description: Response containing an operation object for asynchronous actions.
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
  parameters:
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: HCP service principal access token passed as a Bearer token in the Authorization header.
externalDocs:
  description: HCP Vagrant Box Registry API Documentation
  url: https://developer.hashicorp.com/hcp/api-docs/vagrant-box-registry