NexGen Cloud Virtual Machine API

openapi: 3.2.0
info:
  title: Nexgen Cloud Virtual Machine API
  version: '1.0'
  description: 'Operations tagged Virtual Machine across 2 of this provider''s published API definitions: nexgen-cloud-hyperstack-openapi.json, nexgen-cloud-infrahub-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://infrahub-api.nexgencloud.com/v1
tags:
- name: Virtual Machine
  description: 'A virtual machine on Hyperstack is a single-tenant compute instance backed by dedicated GPU and CPU resources. Each VM runs in a region, attaches a root volume and optional data volumes, and is protected by an environment-scoped firewall. Most workflows follow this lifecycle: deploy → attach data volumes → run workload → snapshot → terminate. For long-running development VMs, hibernation is the cost-effective alternative to termination.'
paths:
  /core/firewalls/{firewall_id}/update-attachments:
    post:
      tags:
      - Virtual Machine
      summary: Attach firewalls to VMs
      description: Attaches an existing firewall to one or more virtual machines. Include the firewall ID in the path, and the IDs of the virtual machines to which it is  being added in the request body, as detailed below.
      operationId: Attach_firewall_to_Vms
      parameters:
      - name: firewall_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the firewall.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachFirewallWithVM'
              example:
                vms:
                - 793869
              properties: {}
            example:
              vms:
              - 793869
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseModel'
              example:
                status: true
                message: Firewall attachments with VMs are scheduled.
              examples:
                default:
                  summary: Successful response
                  value:
                    status: true
                    message: Firewall attachments with VMs are scheduled.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples: {}
      security:
      - apiKey: []
    servers:
    - url: https://infrahub-api.nexgencloud.com/v1
  /core/virtual-machines:
    get:
      tags:
      - Virtual Machine
      summary: List virtual machines
      description: Returns a list of your existing virtual machines, providing configuration details for each. The list is sorted by creation date, with the oldest virtual machines displayed first.
      operationId: List_Vms
      parameters:
      - name: page
        in: query
        schema:
          type: integer
        description: Page number to retrieve.
      - name: pageSize
        in: query
        schema:
          type: integer
        description: Number of items to return per page.
      - name: search
        in: query
        schema:
          type: string
        description: Filter results by case-insensitive substring match against the resource name.
      - name: environment
        in: query
        schema:
          type: string
        description: Filter results to a specific environment by name.
      - name: exclude_firewalls
        in: query
        description: Comma-separated list of Security Group IDs to ignore instances attached
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
      - name: exact_environment_match
        in: query
        description: Flag to filter environment by exact match instead of partial match
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instances'
              example:
                status: true
                message: Getting VMs successful
                page: null
                page_size: null
                count: 3
                instances:
                - id: 7613
                  name: example-restored-1787
                  status: ACTIVE
                  environment:
                    id: 3287
                    name: example-environment
                    org_id: 6190
                    region: NORWAY-1
                    features:
                      network_optimised: false
                      green_status: GREEN
                  image: null
                  flavor:
                    id: 1402
                    name: n1-cpu-small
                    cpu: 4
                    ram: 4
                    disk: 100
                    ephemeral: 0
                    gpu: ''
                    gpu_count: 0
                    labels: []
                    features:
                      network_optimised: false
                      no_reboot: false
                      no_hibernation: false
                      no_snapshot: false
                      local_storage_only: false
                      api_only: false
                  os: Ubuntu Server 24.04 LTS (Noble Numbat)
                  keypair:
                    name: example-keypair
                  volume_attachments: []
                  power_state: RUNNING
                  vm_state: active
                  fixed_ip: 192.0.2.42
                  floating_ip: null
                  floating_ip_status: NO FLOATING IP
                  security_rules:
                  - id: 2058
                    direction: egress
                    protocol: any
                    port_range_min: 1
                    port_range_max: 65535
                    ethertype: IPv6
                    remote_ip_prefix: 0.0.0.0/0
                    status: SUCCESS
                    created_at: '2026-05-07T11:47:30Z'
                  - id: 5341
                    direction: egress
                    protocol: any
                    port_range_min: 1
                    port_range_max: 65535
                    ethertype: IPv4
                    remote_ip_prefix: 0.0.0.0/0
                    status: SUCCESS
                    created_at: '2026-05-06T14:32:11Z'
                  callback_url: null
                  locked: false
                  contract_id: null
                  labels: []
                  created_at: '2026-05-06T15:18:42Z'
                  features:
                    network_optimised: false
                    green_status: GREEN
                  is_snapshotting: false
                  cluster_id: null
                  port_randomization: true
                  port_randomization_status: NO_FLOATING_IP
                  requires_public_ip: false
              examples:
                default:
                  summary: Successful response
                  value:
                    status: true
                    message: Getting VMs successful
                    page: null
                    page_size: null
                    count: 3
                    instances:
                    - id: 7613
                      name: example-restored-1787
                      status: ACTIVE
                      environment:
                        id: 3287
                        name: example-environment
                        org_id: 6190
                        region: NORWAY-1
                        features:
                          network_optimised: false
                          green_status: GREEN
                      image: null
                      flavor:
                        id: 1402
                        name: n1-cpu-small
                        cpu: 4
                        ram: 4
                        disk: 100
                        ephemeral: 0
                        gpu: ''
                        gpu_count: 0
                        labels: []
                        features:
                          network_optimised: false
                          no_reboot: false
                          no_hibernation: false
                          no_snapshot: false
                          local_storage_only: false
                          api_only: false
                      os: Ubuntu Server 24.04 LTS (Noble Numbat)
                      keypair:
                        name: example-keypair
                      volume_attachments: []
                      power_state: RUNNING
                      vm_state: active
                      fixed_ip: 192.0.2.42
                      floating_ip: null
                      floating_ip_status: NO FLOATING IP
                      security_rules:
                      - id: 2058
                        direction: egress
                        protocol: any
                        port_range_min: 1
                        port_range_max: 65535
                        ethertype: IPv6
                        remote_ip_prefix: 0.0.0.0/0
                        status: SUCCESS
                        created_at: '2026-05-07T11:47:30Z'
                      - id: 5341
                        direction: egress
                        protocol: any
                        port_range_min: 1
                        port_range_max: 65535
                        ethertype: IPv4
                        remote_ip_prefix: 0.0.0.0/0
                        status: SUCCESS
                        created_at: '2026-05-06T14:32:11Z'
                      callback_url: null
                      locked: false
                      contract_id: null
                      labels: []
                      created_at: '2026-05-06T15:18:42Z'
                      features:
                        network_optimised: false
                        green_status: GREEN
                      is_snapshotting: false
                      cluster_id: null
                      port_randomization: true
                      port_randomization_status: NO_FLOATING_IP
                      requires_public_ip: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples: {}
      security:
      - apiKey: []
    post:
      tags:
      - Virtual Machine
      summary: Create virtual machines
      description: Creates one or more virtual machines with the specified custom configuration and features provided in the request body. For more information about the virtual machine features offered by Hyperstack, see [Custom VM features](https://docs.hyperstack.cloud/docs/virtual-machines/virtual-machine-features).
      operationId: Create_Vms
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Create_Instances_Payload'
              example:
                name: example-vm
                environment_name: example-environment
                image_name: Ubuntu Server 24.04 LTS (Noble Numbat)
                flavor_name: n1-cpu-small
                key_name: example-keypair
                count: 1
                assign_floating_ip: false
              properties: {}
            example:
              count: 1
              environment_name: example-environment
              flavor_name: n1-cpu-small
              key_name: example-keypair
              name: example-vm
              image_name: Ubuntu Server 24.04 LTS (Noble Numbat)
              assign_floating_ip: false
        required: true
      responses:
        '200':
          description: Virtual machine(s) created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInstancesResponse'
              example:
                status: true
                message: VM is scheduled for creation.
                instances:
                - id: 7613
                  name: example-vm
                  status: CREATING
                  environment:
                    id: 3287
                    name: example-environment
                    org_id: 6190
                    region: NORWAY-1
                    features:
                      network_optimised: false
                      green_status: GREEN
                  image:
                    name: Ubuntu Server 24.04 LTS (Noble Numbat)
                  flavor:
                    id: 1402
                    name: n1-cpu-small
                    cpu: 4
                    ram: 4
                    disk: 100
                    ephemeral: 0
                    gpu: ''
                    gpu_count: 0
                    labels: []
                    features:
                      network_optimised: false
                      no_reboot: false
                      no_hibernation: false
                      no_snapshot: false
                      local_storage_only: false
                      api_only: false
                  os: Ubuntu Server 24.04 LTS (Noble Numbat)
                  keypair:
                    name: example-keypair
                  volume_attachments: []
                  power_state: null
                  vm_state: null
                  fixed_ip: null
                  floating_ip: null
                  floating_ip_status: NO FLOATING IP
                  security_rules: []
                  callback_url: null
                  locked: false
                  contract_id: null
                  labels: []
                  created_at: '2026-05-06T15:18:42Z'
                  features:
                    network_optimised: false
                    green_status: GREEN
                  is_snapshotting: false
                  cluster_id: null
                  port_randomization: true
                  port_randomization_status: NO_FLOATING_IP
                  requires_public_ip: false
              examples:
                default:
                  summary: Successful response
                  value:
                    status: true
                    message: VM is scheduled for creation.
                    instances:
                    - id: 7613
                      name: example-vm
                      status: CREATING
                      environment:
                        id: 3287
                        name: example-environment
                        org_id: 6190
                        region: NORWAY-1
                        features:
                          network_optimised: false
                          green_status: GREEN
                      image:
                        name: Ubuntu Server 24.04 LTS (Noble Numbat)
                      flavor:
                        id: 1402
                        name: n1-cpu-small
                        cpu: 4
                        ram: 4
                        disk: 100
                        ephemeral: 0
                        gpu: ''
                        gpu_count: 0
                        labels: []
                        features:
                          network_optimised: false
                          no_reboot: false
                          no_hibernation: false
                          no_snapshot: false
                          local_storage_only: false
                          api_only: false
                      os: Ubuntu Server 24.04 LTS (Noble Numbat)
                      keypair:
                        name: example-keypair
                      volume_attachments: []
                      power_state: null
                      vm_state: null
                      fixed_ip: null
                      floating_ip: null
                      floating_ip_status: NO FLOATING IP
                      security_rules: []
                      callback_url: null
                      locked: false
                      contract_id: null
                      labels: []
                      created_at: '2026-05-06T15:18:42Z'
                      features:
                        network_optimised: false
                        green_status: GREEN
                      is_snapshotting: false
                      cluster_id: null
                      port_randomization: true
                      port_randomization_status: NO_FLOATING_IP
                      requires_public_ip: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples: {}
      security:
      - apiKey: []
    servers:
    - url: https://infrahub-api.nexgencloud.com/v1
  /core/virtual-machines/contract/{contract_id}/virtual-machines:
    get:
      tags:
      - Virtual Machine
      summary: Retrieve virtual machines associated with a contract
      description: Retrieves a list of virtual machines associated with a contract, providing details such as virtual machine name, timestamp, flavor name, and other relevant information. Please provide the ID of the relevant contract in the path.
      operationId: Get_contract_Vms
      parameters:
      - name: contract_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the customer contract.
      - name: page
        in: query
        description: Page number of results to return.
        schema:
          type: integer
      - name: pageSize
        in: query
        description: Data Per Page
        schema:
          type: integer
      - name: search
        in: query
        description: Search By Instance ID or Name
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractInstancesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        '500':
          description: Internal Server Error
          content: {}
      security:
      - apiKey: []
    servers:
    - url: https://infrahub-api.nexgencloud.com/v1
  /core/virtual-machines/name-availability/{name}:
    get:
      tags:
      - Virtual Machine
      summary: Fetch virtual machine name availability
      description: Check if a Virtual Machine name is available.
      operationId: Check_VM_name_availability
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: Virtual machine name to check for availability.
      - name: count
        in: query
        description: Number of instances to check availability for.
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameAvailableModel'
              example:
                name: example-availability-check
                available: true
                message: This name is available
              examples:
                default:
                  summary: Successful response
                  value:
                    name: example-availability-check
                    available: true
                    message: This name is available
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples: {}
      security:
      - apiKey: []
    servers:
    - url: https://infrahub-api.nexgencloud.com/v1
  /core/virtual-machines/{vm_id}:
    get:
      tags:
      - Virtual Machine
      summary: Retrieve virtual machine details
      description: Retrieves the details of an existing virtual machine. Provide the virtual machine ID in the path, and Hyperstack will return information about the corresponding VM.
      operationId: Get_VM
      parameters:
      - name: vm_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the vm.
      responses:
        '200':
          description: Virtual machine details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                status: true
                message: Getting VM detail successful
                instance:
                  id: 3287
                  name: example-vm
                  status: DELETING
                  environment:
                    id: 8429
                    name: example-environment
                    org_id: 1129
                    region: NORWAY-1
                    features:
                      network_optimised: false
                      green_status: GREEN
                  image:
                    name: Ubuntu Server 24.04 LTS (Noble Numbat)
                  flavor:
                    id: 9876
                    name: n1-cpu-small
                    cpu: 4
                    ram: 4
                    disk: 100
                    ephemeral: 0
                    gpu: ''
                    gpu_count: 0
                    labels: []
                    features:
                      network_optimised: false
                      no_reboot: false
                      no_hibernation: false
                      no_snapshot: false
                      local_storage_only: false
                      api_only: false
                  os: Ubuntu Server 24.04 LTS (Noble Numbat)
                  keypair:
                    name: example-keypair
                  volume_attachments: []
                  power_state: RUNNING
                  vm_state: active
                  fixed_ip: 192.0.2.118
                  floating_ip: ''
                  floating_ip_status: NO FLOATING IP
                  security_rules:
                  - id: 5341
                    direction: egress
                    protocol: any
                    port_range_min: 1
                    port_range_max: 65535
                    ethertype: IPv6
                    remote_ip_prefix: 0.0.0.0/0
                    status: SUCCESS
                    created_at: '2026-05-06T14:32:11Z'
                  - id: 7613
                    direction: egress
                    protocol: any
                    port_range_min: 1
                    port_range_max: 65535
                    ethertype: IPv4
                    remote_ip_prefix: 0.0.0.0/0
                    status: SUCCESS
                    created_at: '2026-05-06T15:18:42Z'
                  - id: 3287
                    direction: ingress
                    protocol: tcp
                    port_range_min: 22
                    port_range_max: 22
                    ethertype: IPv4
                    remote_ip_prefix: 0.0.0.0/0
                    status: SUCCESS
                    created_at: '2026-05-06T16:04:09Z'
                  callback_url: null
                  locked: false
                  contract_id: null
                  labels:
                  - example-label
                  created_at: '2026-05-06T16:04:09Z'
                  features:
                    network_optimised: false
                    green_status: GREEN
                  excluded_billing: false
                  is_snapshotting: false
                  cluster_id: null
                  port_randomization: true
                  port_randomization_status: NO_FLOATING_IP
                  requires_public_ip: false
              examples:
                default:
                  summary: Successful response
                  value:
                    status: true
                    message: Getting VM detail successful
                    instance:
                      id: 3287
                      name: example-vm
                      status: DELETING
                      environment:
                        id: 8429
                        name: example-environment
                        org_id: 1129
                        region: NORWAY-1
                        features:
                          network_optimised: false
                          green_status: GREEN
                      image:
                        name: Ubuntu Server 24.04 LTS (Noble Numbat)
                      flavor:
                        id: 9876
                        name: n1-cpu-small
                        cpu: 4
                        ram: 4
                        disk: 100
                        ephemeral: 0
                        gpu: ''
                        gpu_count: 0
                        labels: []
                        features:
                          network_optimised: false
                          no_reboot: false
                          no_hibernation: false
                          no_snapshot: false
                          local_storage_only: false
                          api_only: false
                      os: Ubuntu Server 24.04 LTS (Noble Numbat)
                      keypair:
                        name: example-keypair
                      volume_attachments: []
                      power_state: RUNNING
                      vm_state: active
                      fixed_ip: 192.0.2.118
                      floating_ip: ''
                      floating_ip_status: NO FLOATING IP
                      security_rules:
                      - id: 5341
                        direction: egress
                        protocol: any
                        port_range_min: 1
                        port_range_max: 65535
                        ethertype: IPv6
                        remote_ip_prefix: 0.0.0.0/0
                        status: SUCCESS
                        created_at: '2026-05-06T14:32:11Z'
                      - id: 7613
                        direction: egress
                        protocol: any
                        port_range_min: 1
                        port_range_max: 65535
                        ethertype: IPv4
                        remote_ip_prefix: 0.0.0.0/0
                        status: SUCCESS
                        created_at: '2026-05-06T15:18:42Z'
                      - id: 3287
                        direction: ingress
                        protocol: tcp
                        port_range_min: 22
                        port_range_max: 22
                        ethertype: IPv4
                        remote_ip_prefix: 0.0.0.0/0
                        status: SUCCESS
                        created_at: '2026-05-06T16:04:09Z'
                      callback_url: null
                      locked: false
                      contract_id: null
                      labels:
                      - example-label
                      created_at: '2026-05-06T16:04:09Z'
                      features:
                        network_optimised: false
                        green_status: GREEN
                      excluded_billing: false
                      is_snapshotting: false
                      cluster_id: null
                      port_randomization: true
                      port_randomization_status: NO_FLOATING_IP
                      requires_public_ip: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples: {}
        '404':
          description: 'Not Found


            Common cause: `error_reason: not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
              examples:
                default:
                  summary: Not Found
                  value:
                    status: false
                    message: VM 793869 does not exists.
                    error_reason: not_found
              example:
                status: false
                message: VM 793869 does not exists.
                error_reason: not_found
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples: {}
      security:
      - apiKey: []
    delete:
      tags:
      - Virtual Machine
      summary: Delete virtual machine
      description: Permanently deletes a virtual machine. Supply the virtual machine ID in the path to delete the specified virtual machine.
      operationId: Delete_VM
      parameters:
      - name: vm_id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the vm.
      responses:
        '200':
          description: Virtual machine deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/comp

# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nexgen-cloud/refs/heads/main/openapi/nexgen-cloud-virtual-machine-api-openapi.yml