> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/api-reference/vm-service/vm.md).

# VM

## List VMs

> Retrieves a paginated list of virtual machines for a specific project.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"ListLimit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size for list endpoints (default 20, maximum 100)."},"VMListResponse":{"type":"object","description":"Paginated list of VMs.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VMResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}}},"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"PaginationResponse":{"type":"object","description":"Pagination metadata.","properties":{"total_items":{"type":"integer","description":"Total number of items across all pages."},"total_pages":{"type":"integer","description":"Total number of pages."},"current_page":{"type":"integer","description":"Current page number."},"items_per_page":{"type":"integer","description":"Number of items per page."}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms":{"get":{"tags":["VM"],"summary":"List VMs","description":"Retrieves a paginated list of virtual machines for a specific project.","operationId":"listVMs","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination (starts from 1)."},{"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/ListLimit"},"description":"Number of items to return per page (default 20, maximum 100)."}],"responses":{"200":{"description":"A paginated list of VMs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMListResponse"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The project was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a VM

> Creates a new virtual machine with the specified compute, root disk, optional GPU, and network configuration.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"CreateVMRequest":{"type":"object","description":"Request body for creating a new VM.","required":["name","region_id","vm_config_id","plan_id","root_disk"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/ResourceName"}],"description":"User-defined display name for the VM."},"region_id":{"type":"string","description":"The region ID where the VM will be deployed."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration to use for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations need to be attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"root_disk":{"type":"object","properties":{"attach_disk_request":{"$ref":"#/components/schemas/AttachDiskRequest"},"create_disk_request":{"$ref":"#/components/schemas/CreateRootDiskRequest"}},"oneOf":[{"required":["attach_disk_request"]},{"required":["create_disk_request"]}]},"data_disks":{"type":"object","description":"Additional data disks to attach or create for the VM.","properties":{"attached_disks":{"type":"array","items":{"$ref":"#/components/schemas/AttachDiskRequest"},"description":"Additional data disks to attach to the VM.","maxItems":4},"create_disks":{"type":"array","items":{"$ref":"#/components/schemas/CreateDataDiskRequest"},"description":"Additional data disks to create for the VM.","maxItems":4}}},"ssh_keys":{"type":"array","description":"SSH public keys for VM access. Maximum 10 keys per VM.\nKeys are installed on the ubuntu user via cloud-init and enable SSH on port 22 when a public IP is allocated.\n","minItems":0,"maxItems":10,"items":{"type":"string","pattern":"^(ssh-rsa|ssh-ed25519)\\s+[A-Za-z0-9+/]+[=]{0,2}(\\s+.*)?$","minLength":50,"maxLength":2000,"description":"SSH public key in OpenSSH format. Supported key types:\n- ssh-rsa (RSA keys, minimum 2048 bits recommended)\n- ssh-ed25519 (Ed25519 keys, 256 bits)\n"},"uniqueItems":true},"exposed_ports":{"type":"array","description":"Inbound ports to expose on the VM public IP. Maximum 10 ports per VM.\nEach entry must use tcp or udp. Port numbers must be between 1 and 65535.\nPort 22 must not be listed; use ssh_keys for SSH access instead.\nDuplicate port and protocol pairs are not allowed.\n","minItems":0,"maxItems":10,"uniqueItems":true,"items":{"$ref":"#/components/schemas/ExposedPort"}},"delete_root_disk":{"type":"boolean","default":false,"description":"If true, VM deletion removes the managed root disk (create_disk_request only); otherwise detach only. Ignored for attach_disk_request."}}},"ResourceName":{"type":"string","description":"DNS-1123 label compatible resource name.","pattern":"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$","maxLength":20},"AttachDiskRequest":{"type":"object","description":"Attach an existing disk to the VM.","required":["disk_id"],"properties":{"disk_id":{"type":"string","format":"uuid","description":"UUID of an existing disk to attach."}}},"CreateRootDiskRequest":{"type":"object","description":"Create a new root disk for the VM by cloning a platform image.","required":["name","size_gb","image_id"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/ResourceName"}],"description":"Name of the disk."},"size_gb":{"type":"integer","minimum":20,"maximum":2048,"description":"Size of the root disk in gigabytes. Must be between 20 GB and 2048 GB (2 TB)."},"image_id":{"type":"string","description":"ID of the platform image to clone as the root disk (e.g. Ubuntu 24.04 LTS)."}}},"CreateDataDiskRequest":{"type":"object","description":"Create a new disk for the VM.","required":["name","type","size_gb"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/ResourceName"}],"description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","minimum":10,"maximum":2048,"description":"Size of the data disk in gigabytes. Must be between 10 GB and 2048 GB (2 TB)."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms":{"post":{"tags":["VM"],"summary":"Create a VM","description":"Creates a new virtual machine with the specified compute, root disk, optional GPU, and network configuration.","operationId":"createVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVMRequest"}}}},"responses":{"201":{"description":"The VM was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMResponse"}}}},"400":{"description":"The request payload is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The project, region ID, or image was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The root disk is already attached to another VM.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get VM by ID

> Fetches the details of a specific VM by its unique identifier.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms/{vm_id}":{"get":{"tags":["VM"],"summary":"Get VM by ID","description":"Fetches the details of a specific VM by its unique identifier.","operationId":"getVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"vm_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the VM."}],"responses":{"200":{"description":"Detailed information about the VM.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMResponse"}}}},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A VM with the specified ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a VM

> Permanently deletes a specific VM by its unique ID.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms/{vm_id}":{"delete":{"tags":["VM"],"summary":"Delete a VM","description":"Permanently deletes a specific VM by its unique ID.","operationId":"deleteVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"vm_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the VM to delete."}],"responses":{"202":{"description":"The VM deletion request was accepted."},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A VM with the specified ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List root disk volumes

> Returns a paginated list of root disk volumes for the project that are not deleted.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"ListLimit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size for list endpoints (default 20, maximum 100)."},"RootDiskVolumeListResponse":{"type":"object","description":"Paginated list of root disk volumes.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RootDiskVolumeResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}}},"RootDiskVolumeResponse":{"type":"object","description":"Root disk volume managed by the platform for a project (clone or attach source).","required":["id","name","org_id","project_id","region","size_gb","image_id","volume_mode","plan_id","status","is_attached","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the root disk volume."},"name":{"type":"string","description":"Display name of the volume."},"org_id":{"type":"string","description":"Owning organization identifier."},"project_id":{"type":"string","description":"Owning project identifier."},"region":{"type":"string","description":"Region where the volumes cluster resources live."},"size_gb":{"type":"integer","description":"Size of the volume in gigabytes."},"image_id":{"type":"string","description":"Platform OS image this root disk was created from."},"volume_mode":{"type":"string","description":"Volume mode (e.g. filesystem or block)."},"plan_id":{"type":"string","description":"Product plan associated with this volume."},"status":{"type":"string","description":"Lifecycle status of the volume (pending, provisioning, ready, failed, deleting)."},"message":{"type":"string","nullable":true,"description":"Optional detail about the current volume status."},"is_attached":{"type":"boolean","description":"True when this root disk is currently attached to a VM (vm_id is set)."},"vm_id":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the VM this root disk is attached to when is_attached is true; otherwise null."},"created_at":{"type":"string","format":"date-time","description":"When the volume record was created."},"updated_at":{"type":"string","format":"date-time","description":"When the volume record was last updated."}}},"PaginationResponse":{"type":"object","description":"Pagination metadata.","properties":{"total_items":{"type":"integer","description":"Total number of items across all pages."},"total_pages":{"type":"integer","description":"Total number of pages."},"current_page":{"type":"integer","description":"Current page number."},"items_per_page":{"type":"integer","description":"Number of items per page."}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/root_disks":{"get":{"tags":["VM"],"summary":"List root disk volumes","description":"Returns a paginated list of root disk volumes for the project that are not deleted.","operationId":"listRootDiskVolumes","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination (starts from 1)."},{"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/ListLimit"},"description":"Number of items to return per page (default 20, maximum 100)."}],"responses":{"200":{"description":"Paginated list of root disk volumes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootDiskVolumeListResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get root disk volume by ID

> Returns details for a single root disk volume in the project.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"RootDiskVolumeResponse":{"type":"object","description":"Root disk volume managed by the platform for a project (clone or attach source).","required":["id","name","org_id","project_id","region","size_gb","image_id","volume_mode","plan_id","status","is_attached","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the root disk volume."},"name":{"type":"string","description":"Display name of the volume."},"org_id":{"type":"string","description":"Owning organization identifier."},"project_id":{"type":"string","description":"Owning project identifier."},"region":{"type":"string","description":"Region where the volumes cluster resources live."},"size_gb":{"type":"integer","description":"Size of the volume in gigabytes."},"image_id":{"type":"string","description":"Platform OS image this root disk was created from."},"volume_mode":{"type":"string","description":"Volume mode (e.g. filesystem or block)."},"plan_id":{"type":"string","description":"Product plan associated with this volume."},"status":{"type":"string","description":"Lifecycle status of the volume (pending, provisioning, ready, failed, deleting)."},"message":{"type":"string","nullable":true,"description":"Optional detail about the current volume status."},"is_attached":{"type":"boolean","description":"True when this root disk is currently attached to a VM (vm_id is set)."},"vm_id":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the VM this root disk is attached to when is_attached is true; otherwise null."},"created_at":{"type":"string","format":"date-time","description":"When the volume record was created."},"updated_at":{"type":"string","format":"date-time","description":"When the volume record was last updated."}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/root_disks/{root_disk_id}":{"get":{"tags":["VM"],"summary":"Get root disk volume by ID","description":"Returns details for a single root disk volume in the project.","operationId":"getRootDiskVolume","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"root_disk_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the root disk."}],"responses":{"200":{"description":"Root disk volume details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootDiskVolumeResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The root disk volume was not found in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a root disk volume

> Queues deletion for an unattached root disk; completion is asynchronous.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/root_disks/{root_disk_id}":{"delete":{"tags":["VM"],"summary":"Delete a root disk volume","description":"Queues deletion for an unattached root disk; completion is asynchronous.","operationId":"deleteRootDiskVolume","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"root_disk_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the root disk to delete."}],"responses":{"202":{"description":"Root disk deletion request accepted."},"400":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The root disk volume was not found in this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The root disk volume is still attached to a VM.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Start a VM

> Starts a stopped VM. Has no effect if the VM is already running.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms/{vm_id}/start":{"post":{"tags":["VM"],"summary":"Start a VM","description":"Starts a stopped VM. Has no effect if the VM is already running.","operationId":"startVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"vm_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the VM to start."}],"responses":{"202":{"description":"The start request was accepted. Returns the VM with its current status (may still be transitioning to running).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMResponse"}}}},"400":{"description":"The request is invalid or VM is not in a state that allows start.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A VM with the specified ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Stop a VM

> Stops a running VM. Has no effect if the VM is already stopped.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms/{vm_id}/stop":{"post":{"tags":["VM"],"summary":"Stop a VM","description":"Stops a running VM. Has no effect if the VM is already stopped.","operationId":"stopVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"vm_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the VM to stop."}],"responses":{"202":{"description":"The stop request was accepted. Returns the VM with its current status (may still be transitioning to stopped).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMResponse"}}}},"400":{"description":"The request is invalid or VM is not in a state that allows stop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A VM with the specified ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Restart a VM

> Restarts a running VM. Has no effect if the VM is not running.

```json
{"openapi":"3.0.3","info":{"title":"VM Service API","version":"0.1.0"},"servers":[{"url":"https://api.ai.neevcloud.com/vm","description":"Consolidated public API gateway"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication."}},"schemas":{"VMResponse":{"type":"object","description":"Full VM representation as returned by the API.","required":["id","name","region_id","status","vm_config_id","plan_id","image_id","delete_root_disk","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the VM."},"name":{"type":"string","description":"The user-defined name of the VM."},"region_id":{"type":"string","description":"The region ID where the VM is deployed."},"delete_root_disk":{"type":"boolean","description":"Whether VM deletion also removes the platform-managed root disk (create_disk_request only)."},"status":{"$ref":"#/components/schemas/VMStatus"},"message":{"type":"string","nullable":true,"description":"Optional detail about the current VM status (e.g. provisioning step or failure reason)."},"vm_config_id":{"type":"string","description":"The ID of the VM configuration used for the VM."},"gpu_config_count":{"type":"integer","description":"The number of GPU configurations attached to the VM."},"plan_id":{"type":"string","description":"The pricing plan ID for billing the VM."},"image_id":{"type":"string","description":"The ID of the platform image the root disk was cloned from. Always set — inherited from the root disk, whether newly created or attached."},"root_disk":{"$ref":"#/components/schemas/DiskResponse","description":"Root (boot) disk for the VM."},"data_disks":{"type":"array","nullable":true,"description":"Additional data disks attached to the VM.","items":{"$ref":"#/components/schemas/DiskResponse"}},"public_ip":{"type":"string","nullable":true,"description":"Public IP allocated for the VM when external networking is enabled and ready."},"exposed_ports":{"type":"array","description":"Ports exposed on the VM public IP for inbound access.","items":{"$ref":"#/components/schemas/ExposedPort"}},"created_at":{"type":"string","format":"date-time","description":"When the VM was created."},"updated_at":{"type":"string","format":"date-time","description":"When the VM was last updated."}}},"VMStatus":{"type":"string","description":"Current lifecycle status of the VM.","enum":["pending","provisioning","starting","running","stopping","stopped","restarting","deleting","deleted","failed"]},"DiskResponse":{"type":"object","description":"Disk attachment as returned by the API (root or data).","required":["id","name","type","size_gb"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the disk."},"name":{"type":"string","description":"Name of the disk."},"type":{"$ref":"#/components/schemas/DataDiskType"},"size_gb":{"type":"integer","description":"Size in gigabytes."}}},"DataDiskType":{"type":"string","description":"Type of the data disk.","enum":["block","filesystem"]},"ExposedPort":{"type":"object","description":"Inbound port exposed on the VM public IP.","required":["port","protocol"],"properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"Port number inside the VM that the guest process listens on, except for port 22 which is reserved for SSH when ssh_keys are provided."},"protocol":{"type":"string","description":"Layer-4 protocol for an exposed inbound port.","enum":["tcp","udp"]}}},"ErrorResponse":{"type":"object","description":"Standard format for error responses.","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/orgs/{org_id}/projects/{project_id}/vms/{vm_id}/restart":{"post":{"tags":["VM"],"summary":"Restart a VM","description":"Restarts a running VM. Has no effect if the VM is not running.","operationId":"restartVM","parameters":[{"in":"path","name":"org_id","required":true,"schema":{"type":"string"},"description":"The organization identifier."},{"in":"path","name":"project_id","required":true,"schema":{"type":"string"},"description":"The project identifier."},{"in":"path","name":"vm_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the VM to restart."}],"responses":{"202":{"description":"The restart request was accepted. Returns the VM with its current status (may still be transitioning).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VMResponse"}}}},"400":{"description":"The request is invalid or VM is not in a state that allows restart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A VM with the specified ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"An unexpected internal server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ai.neevcloud.com/api-reference/vm-service/vm.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.