openapi: 3.0.1
info:
  title: CUDO Compute API
  description: >-
    REST API for the CUDO Compute global GPU and cloud compute platform and
    marketplace. The API is versioned, resource-oriented, and speaks JSON over
    HTTPS. It provisions and manages virtual machines, machine types, data
    centers, disks and snapshots, networks and security groups, images, SSH
    keys, object storage, and billing. A parallel gRPC API exposes the same
    services. Authentication uses a Bearer API key created in the CUDO Compute
    dashboard; requests without a valid key return 401 UNAUTHENTICATED.
  termsOfService: https://www.cudocompute.com/legal/terms-of-service
  contact:
    name: CUDO Compute Support
    url: https://www.cudocompute.com/contact
  version: '1.0.0'
servers:
  - url: https://rest.compute.cudo.org
security:
  - bearerAuth: []
tags:
  - name: Virtual Machines
  - name: Machine Types
  - name: Data Centers
  - name: Disks
  - name: Networks
  - name: Images
  - name: SSH Keys
  - name: Billing
paths:
  /v1/projects/{projectId}/vm:
    post:
      operationId: createVM
      tags:
        - Virtual Machines
      summary: Create a virtual machine
      description: Provisions a new CPU- or GPU-backed virtual machine in a project.
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVMBody'
      responses:
        '200':
          description: Virtual machine created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVMResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms:
    get:
      operationId: listVMs
      tags:
        - Virtual Machines
      summary: List virtual machines
      parameters:
        - $ref: '#/components/parameters/projectId'
        - name: pageSize
          in: query
          schema:
            type: integer
        - name: startAfter
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of virtual machines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVMsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}:
    get:
      operationId: getVM
      tags:
        - Virtual Machines
      summary: Get a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested virtual machine
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VM'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/start:
    post:
      operationId: startVM
      tags:
        - Virtual Machines
      summary: Start a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Start acknowledged
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/stop:
    post:
      operationId: stopVM
      tags:
        - Virtual Machines
      summary: Stop a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Stop acknowledged
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/reboot:
    post:
      operationId: rebootVM
      tags:
        - Virtual Machines
      summary: Reboot a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Reboot acknowledged
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/resize:
    post:
      operationId: resizeVM
      tags:
        - Virtual Machines
      summary: Resize a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vcpus:
                  type: integer
                memoryGib:
                  type: integer
      responses:
        '200':
          description: Resize acknowledged
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/terminate:
    post:
      operationId: terminateVM
      tags:
        - Virtual Machines
      summary: Terminate a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Terminate acknowledged
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/connect:
    get:
      operationId: connectVM
      tags:
        - Virtual Machines
      summary: Get virtual machine connection details
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Connection details
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/vms/{id}/monitor:
    get:
      operationId: monitorVM
      tags:
        - Virtual Machines
      summary: Get virtual machine monitoring metrics
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Monitoring metrics
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/vms/gpu-models:
    get:
      operationId: listVMGpuModels
      tags:
        - Machine Types
      summary: List GPU models
      responses:
        '200':
          description: Available GPU models
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/vms/machine-types:
    get:
      operationId: listVMMachineTypes
      tags:
        - Machine Types
      summary: List machine types
      responses:
        '200':
          description: Available machine types
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-centers/{dataCenterId}/machine-types:
    get:
      operationId: listDataCenterMachineTypes
      tags:
        - Machine Types
      summary: List machine types in a data center
      parameters:
        - $ref: '#/components/parameters/dataCenterId'
      responses:
        '200':
          description: Machine types in the data center
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-centers/{dataCenterId}/machine-type-prices:
    get:
      operationId: listMachineTypePrices
      tags:
        - Machine Types
      summary: List machine-type prices in a data center
      parameters:
        - $ref: '#/components/parameters/dataCenterId'
      responses:
        '200':
          description: Machine-type prices
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-centers:
    get:
      operationId: listDataCenters
      tags:
        - Data Centers
      summary: List data centers
      responses:
        '200':
          description: A list of data centers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataCentersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-centers/{id}:
    get:
      operationId: getDataCenter
      tags:
        - Data Centers
      summary: Get a data center
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested data center
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataCenter'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/regions:
    get:
      operationId: listRegions
      tags:
        - Data Centers
      summary: List regions
      responses:
        '200':
          description: A list of regions
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/disks:
    get:
      operationId: listDisks
      tags:
        - Disks
      summary: List storage disks
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: A list of disks
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createStorageDisk
      tags:
        - Disks
      summary: Create a storage disk
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStorageDiskBody'
      responses:
        '200':
          description: Disk created
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/disks/{id}:
    get:
      operationId: getDisk
      tags:
        - Disks
      summary: Get a storage disk
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested disk
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disk'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteDisk
      tags:
        - Disks
      summary: Delete a storage disk
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Disk deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/disk/{id}/attach:
    patch:
      operationId: attachStorageDisk
      tags:
        - Disks
      summary: Attach a storage disk to a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vmId:
                  type: string
      responses:
        '200':
          description: Disk attached
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/disk/{id}/detach:
    put:
      operationId: detachStorageDisk
      tags:
        - Disks
      summary: Detach a storage disk from a virtual machine
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Disk detached
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/disks/{id}/snapshots:
    get:
      operationId: listDiskSnapshots
      tags:
        - Disks
      summary: List disk snapshots
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: A list of disk snapshots
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDiskSnapshot
      tags:
        - Disks
      summary: Create a disk snapshot
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Snapshot created
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteDiskSnapshot
      tags:
        - Disks
      summary: Delete a disk snapshot
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Snapshot deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/networks:
    get:
      operationId: listNetworks
      tags:
        - Networks
      summary: List networks
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: A list of networks
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createNetwork
      tags:
        - Networks
      summary: Create a network
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetworkBody'
      responses:
        '200':
          description: Network created
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/networks/{id}:
    get:
      operationId: getNetwork
      tags:
        - Networks
      summary: Get a network
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested network
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteNetwork
      tags:
        - Networks
      summary: Delete a network
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Network deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/networks/{id}/start:
    post:
      operationId: startNetwork
      tags:
        - Networks
      summary: Start a network
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Network started
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/networks/{id}/stop:
    post:
      operationId: stopNetwork
      tags:
        - Networks
      summary: Stop a network
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Network stopped
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/networks/security-groups:
    get:
      operationId: listSecurityGroups
      tags:
        - Networks
      summary: List security groups
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: A list of security groups
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/images:
    get:
      operationId: listPrivateVMImages
      tags:
        - Images
      summary: List private VM images
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: A list of private VM images
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPrivateVMImage
      tags:
        - Images
      summary: Create a private VM image
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                vmId:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: Private VM image created
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/projects/{projectId}/images/{id}:
    get:
      operationId: getPrivateVMImage
      tags:
        - Images
      summary: Get a private VM image
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested private VM image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deletePrivateVMImage
      tags:
        - Images
      summary: Delete a private VM image
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Private VM image deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/vms/public-images:
    get:
      operationId: listPublicVMImages
      tags:
        - Images
      summary: List public VM images
      responses:
        '200':
          description: A list of public VM images
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/ssh-keys:
    get:
      operationId: listSSHKeys
      tags:
        - SSH Keys
      summary: List SSH keys
      responses:
        '200':
          description: A list of SSH keys
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSSHKey
      tags:
        - SSH Keys
      summary: Create an SSH key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                publicKey:
                  type: string
      responses:
        '200':
          description: SSH key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/ssh-keys/{id}:
    get:
      operationId: getSSHKey
      tags:
        - SSH Keys
      summary: Get an SSH key
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested SSH key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SshKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteSSHKey
      tags:
        - SSH Keys
      summary: Delete an SSH key
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: SSH key deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/project/{projectId}/ssh-keys:
    get:
      operationId: listProjectSSHKeys
      tags:
        - SSH Keys
      summary: List SSH keys available to a project
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: A list of project SSH keys
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing-accounts:
    get:
      operationId: listBillingAccounts
      tags:
        - Billing
      summary: List billing accounts
      responses:
        '200':
          description: A list of billing accounts
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBillingAccount
      tags:
        - Billing
      summary: Create a billing account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
      responses:
        '200':
          description: Billing account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing-accounts/{id}:
    get:
      operationId: getBillingAccount
      tags:
        - Billing
      summary: Get a billing account
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The requested billing account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteBillingAccount
      tags:
        - Billing
      summary: Delete a billing account
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Billing account deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing-accounts/{id}/details:
    get:
      operationId: getBillingAccountDetails
      tags:
        - Billing
      summary: Get billing account details
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Billing account details
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/billing-accounts/invoices:
    get:
      operationId: listBillingAccountInvoices
      tags:
        - Billing
      summary: List billing account invoices
      responses:
        '200':
          description: A list of invoices
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A CUDO Compute API key passed as a Bearer token in the
        Authorization header, e.g. `Authorization: Bearer $CUDO_API_KEY`.
        Create keys in the CUDO Compute dashboard. Missing or invalid keys
        return 401 UNAUTHENTICATED.
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: The project identifier.
      schema:
        type: string
    dataCenterId:
      name: dataCenterId
      in: path
      required: true
      description: The data center identifier.
      schema:
        type: string
    id:
      name: id
      in: path
      required: true
      description: The resource identifier.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed; missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CreateVMBody:
      type: object
      properties:
        dataCenterId:
          type: string
        machineType:
          type: string
        vmId:
          type: string
        startScript:
          type: string
        password:
          type: string
        bootDiskImageId:
          type: string
        vcpus:
          type: integer
        memoryGib:
          type: integer
        gpus:
          type: integer
        cpuModel:
          type: string
        gpuModel:
          type: string
        customSshKeys:
          type: array
          items:
            type: string
        bootDisk:
          $ref: '#/components/schemas/Disk'
    CreateVMResponse:
      type: object
      properties:
        id:
          type: string
        vm:
          $ref: '#/components/schemas/VM'
    ListVMsResponse:
      type: object
      properties:
        vms:
          type: array
          items:
            $ref: '#/components/schemas/VM'
    VM:
      type: object
      properties:
        id:
          type: string
        datacenterId:
          type: string
        machineType:
          type: string
        regionId:
          type: string
        regionName:
          type: string
        externalIpAddress:
          type: string
        internalIpAddress:
          type: string
        publicIpAddress:
          type: string
        memory:
          type: integer
        cpuModel:
          type: string
        vcpus:
          type: integer
        gpuModel:
          type: string
        gpuModelId:
          type: string
        gpuQuantity:
          type: integer
    CreateStorageDiskBody:
      type: object
      properties:
        dataCenterId:
          type: string
        disk:
          $ref: '#/components/schemas/Disk'
    Disk:
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        dataCenterId:
          type: string
        vmId:
          type: string
        sizeGib:
          type: integer
        publicImageId:
          type: string
        privateImageId:
          type: string
        createTime:
          type: string
          format: date-time
    CreateNetworkBody:
      type: object
      properties:
        dataCenterId:
          type: string
        id:
          type: string
        cidrPrefix:
          type: string
    Network:
      type: object
      properties:
        id:
          type: string
        dataCenterId:
          type: string
        ipRange:
          type: string
        gateway:
          type: string
        externalIpAddress:
          type: string
        internalIpAddress:
          type: string
        shortState:
          type: string
        createTime:
          type: string
          format: date-time
    Image:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        displayName:
          type: string
        platform:
          type: string
        sizeGib:
          type: integer
    SshKey:
      type: object
      properties:
        id:
          type: string
        publicKey:
          type: string
        fingerprint:
          type: string
        type:
          type: string
        comment:
          type: string
        createTime:
          type: string
          format: date-time
    DataCenter:
      type: object
      properties:
        id:
          type: string
        regionId:
          type: string
        ipAddresses:
          type: array
          items:
            type: string
        renewableEnergy:
          type: boolean
    ListDataCentersResponse:
      type: object
      properties:
        dataCenters:
          type: array
          items:
            $ref: '#/components/schemas/DataCenter'
    BillingAccount:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        createTime:
          type: string
          format: date-time
        monthlySpend:
          type: string
        creditBalance:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        status:
          type: string