{ "openapi": "3.0.1", "info": { "title": "CS4 Cloud API", "description": "Public data API for CS4 Cloud (ASP.NET Core 8 port of CS4.Cloud.Apx).", "version": "v1" }, "paths": { "/Connection": { "post": { "tags": [ "Data" ], "summary": "Checks core database (and downstream) connectivity. Returns \"OK\" or an error message.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/WebQuery": { "post": { "tags": [ "Data" ], "summary": "Dispatches a single operation selected by the one populated member of rqst\r\n(mirrors the legacy WebQuery contract).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebQueryRqst" } }, "text/json": { "schema": { "$ref": "#/components/schemas/WebQueryRqst" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/WebQueryRqst" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebQueryRspn" } } } } } } }, "/datastores/list": { "post": { "tags": [ "Datastore" ], "summary": "List the tenant's datastores.", "description": "Returns the tenant's datastores across all its hypervisors, or a single hypervisor when\r\n`hypervisorName` is given. A datastore mounted on several hosts appears once per host (each row\r\ncarries its `hostName`), so expect duplicate names differing only by host.\r\n \r\nAuthentication: API key in the body. `hypervisorName` is optional (omit/blank = all hypervisors).\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"hypervisorName\": \"vcenter-prod\" }\r\n \r\nA `hypervisorName` that isn't the tenant's returns HTTP 200 \"failed\" (never another tenant's data).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `items`, or \"failed\" with a message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host (connection store unprovisioned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreDtoInventoryListResult" } } } } } } }, "/datastores/get": { "post": { "tags": [ "Datastore" ], "summary": "Read one datastore by name (returns each per-host mount row).", "description": "Returns every row for the named datastore — one per host it's mounted on — so the result is a list,\r\nnot a single object. Pass `hypervisorName` to disambiguate when the same datastore name exists on\r\nmore than one hypervisor.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"name\": \"datastore1\", \"hypervisorName\": \"vcenter-prod\" }\r\n \r\nA missing/unknown name returns HTTP 200 \"failed\" with an empty `items`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with the datastore's per-host rows in `items`, or \"failed\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreDtoInventoryListResult" } } } } } } }, "/vms/list": { "post": { "tags": [ "GetVm" ], "summary": "List the tenant's VMs (core fields).", "description": "Returns the tenant's live VMs (stale and soft-deleted excluded) across all its hypervisors, or a single\r\nhypervisor when `hypervisorName` is given. Core fields only — power state, vCPU, memory, storage,\r\nhost, guest OS. For a VM's disks and NICs, call `vms/get`.\r\n \r\nPaged: returns at most 25 VMs per page, ordered by VM name. `pageNumber` is 1-based (omit or use\r\n<1 for page 1); a page past the last returns an empty list. Page until you receive fewer than 25 items.\r\n \r\nAuthentication: API key in the body. `hypervisorName` is optional (omit/blank = all hypervisors).\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"hypervisorName\": \"vcenter-prod\", \"pageNumber\": 1 }", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `items`, or \"failed\" with a message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmListItemDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host (connection store unprovisioned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmListItemDtoInventoryListResult" } } } } } } }, "/vms/get": { "post": { "tags": [ "GetVm" ], "summary": "Read one VM's full detail by name.", "description": "Returns the named VM (unique within the tenant, stale/soft-deleted excluded) with its core fields plus\r\nits disks and network adapters — the same data the console's VM detail page shows. Served from the\r\nsynced inventory, not a live hypervisor call.\r\n \r\nAuthentication: API key in the body. `vmName` is the VM's display name.\r\n \r\nSet `syncNow: true` to queue a live inventory refresh for this VM's hypervisor on the engine. The\r\nrefresh is asynchronous — this call still returns the currently-cached detail immediately, with\r\n`refreshQueued` set; re-call after a few seconds to read the refreshed data.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"vmName\": \"web-01\", \"syncNow\": true }\r\n \r\nA missing/unknown/ambiguous name returns HTTP 200 \"failed\" with `virtualMachine` null (not a 404).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetVmRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetVmRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `virtualMachine`, or \"failed\" (bad key, missing/unknown/ambiguous name).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmResult" } } } } } } }, "/vms/sync-status": { "post": { "tags": [ "GetVm" ], "summary": "Poll a queued inventory refresh by its request id.", "description": "Tracks a `vms/get` syncNow refresh to completion. Pass the `refreshRequestId` returned by that\r\ncall; this returns the sync's current lifecycle state (`pending` → `running` → `ok`/\r\n`failed`) plus `isComplete`. The refresh runs on the engine and a full-hypervisor sync can take\r\n~a minute, so poll until `isComplete` is true, then re-call `vms/get` for the refreshed detail.\r\n \r\nAuthentication: API key in the body. Scoped to the key's tenant — an unknown id, or one belonging to a\r\ndifferent tenant, returns \"failed\" (not a 404).\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"requestId\": 42 }", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SyncStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SyncStatusRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with the sync state, or \"failed\" (bad key, missing/unknown id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResult" } } } } } } }, "/hosts/list": { "post": { "tags": [ "Host" ], "summary": "List the tenant's hosts (ESXi hosts / Proxmox nodes).", "description": "There is no host table — a host is derived by grouping the tenant's live VMs by host name. Each row is\r\naggregates over that host's VMs: VM count, powered-on count, total vCPU / memory (MB) / storage (GB),\r\ndatastore count, and last-sync time. Soft-deleted and stale VMs are excluded (so counts may differ\r\nslightly from a view that includes them).\r\n \r\nAuthentication: API key in the body. `hypervisorName` is optional (omit/blank = all hypervisors).\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"hypervisorName\": \"vcenter-prod\" }", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with the derived hosts in `items`, or \"failed\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host (connection store unprovisioned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDtoInventoryListResult" } } } } } } }, "/hosts/get": { "post": { "tags": [ "Host" ], "summary": "Read one host by name, with its aggregates.", "description": "Returns the single derived host whose name matches (case-insensitive), with the same aggregates as the\r\nlist. Pass `hypervisorName` to scope when a host name could appear under more than one hypervisor.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"name\": \"esxi-01.example.com\", \"hypervisorName\": \"vcenter-prod\" }\r\n \r\nA host with no live VMs reporting it returns HTTP 200 \"failed\" with `item` null.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `item`, or \"failed\" (missing/unknown host) with `item` null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDtoInventoryItemResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostDtoInventoryItemResult" } } } } } } }, "/hypervisors/list": { "post": { "tags": [ "Hypervisor" ], "summary": "List the tenant's hypervisors.", "description": "Returns every hypervisor registered for the API key's tenant (enabled or not), with connection status\r\nand, per hypervisor, its host/port — never any credential. Aggregates (last-sync, host/VM counts) are\r\nonly populated by `hypervisors/get`.\r\n \r\nAuthentication: supply your API key in the body (`apiKeyName` + `apiKeySecret`). The key\r\nscopes the result to its tenant; there are no query/path parameters.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\" }\r\n \r\nThe response always returns HTTP 200 with a `status` of \"ok\" or \"failed\" (auth failures included);\r\n503 only when the service's connection store is unprovisioned.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryAuthRequestBody" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InventoryAuthRequestBody" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InventoryAuthRequestBody" } } } }, "responses": { "200": { "description": "Result envelope: `status` \"ok\" with `items`, or \"failed\" with a message (e.g. invalid API key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HypervisorDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host (connection store unprovisioned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HypervisorDtoInventoryListResult" } } } } } } }, "/hypervisors/get": { "post": { "tags": [ "Hypervisor" ], "summary": "Read one hypervisor by name, with its VM/host aggregates.", "description": "Returns the named hypervisor (unique per tenant) plus the aggregates the console shows: most-recent VM\r\nsync time, distinct live-host count, and live VM count. Credentials are never returned.\r\n \r\nAuthentication: API key in the body. `name` is the hypervisor's display name.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"name\": \"vcenter-prod\" }\r\n \r\nA missing/unknown name returns HTTP 200 with `status` \"failed\" and `item` null (not a 404).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetHypervisorRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetHypervisorRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetHypervisorRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `item`, or \"failed\" (bad key, missing/unknown name) with `item` null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HypervisorDtoInventoryItemResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HypervisorDtoInventoryItemResult" } } } } } } }, "/networks/list": { "post": { "tags": [ "Network" ], "summary": "List the tenant's networks / portgroups.", "description": "Returns the tenant's networks across all its hypervisors, or a single hypervisor when\r\n`hypervisorName` is given. Each row carries the hypervisor-native `networkKey` (moref; null on\r\nProxmox) and `type` (STANDARD_PORTGROUP / DISTRIBUTED_PORTGROUP / OPAQUE_NETWORK).\r\n \r\nAuthentication: API key in the body. `hypervisorName` is optional (omit/blank = all hypervisors).\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"hypervisorName\": \"vcenter-prod\" }", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InventoryListRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with `items`, or \"failed\" with a message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host (connection store unprovisioned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDtoInventoryListResult" } } } } } } }, "/networks/get": { "post": { "tags": [ "Network" ], "summary": "Read network(s) by name.", "description": "Returns every network matching the name. A network name can repeat across hypervisors, so without a\r\n`hypervisorName` filter this may return more than one row; pass `hypervisorName` to narrow to\r\none. The result is therefore a list, not a single object.\r\n \r\nExample request body:\r\n \r\n { \"apiKeyName\": \"my-key\", \"apiKeySecret\": \"s3cr3t\", \"name\": \"VM Network\", \"hypervisorName\": \"vcenter-prod\" }\r\n \r\nA missing/unknown name returns HTTP 200 \"failed\" with an empty `items`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetNamedInventoryRequest" } } } }, "responses": { "200": { "description": "Result envelope: \"ok\" with matching networks in `items`, or \"failed\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDtoInventoryListResult" } } } }, "503": { "description": "The VM API is not configured on this host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDtoInventoryListResult" } } } } } } }, "/status": { "get": { "tags": [ "Status" ], "summary": "Reports core database and VBR connectivity.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRspn" } } } } } } }, "/veeam/backup": { "post": { "tags": [ "VeeamTask" ], "summary": "Backs up a VM by name (the engine resolves which job/server protects it, optionally narrowed by zone).\r\nReturns a task id; if Wait=true the call blocks up to WaitTimeoutSeconds for the final result\r\n(including the backup GUID on success), otherwise it returns immediately.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVmRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BackupVmRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/BackupVmRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupTaskResult" } } } } } } }, "/veeam/backup-status": { "post": { "tags": [ "VeeamTask" ], "summary": "Queries a previously queued backup task by its GUID (returned from /veeam/backup).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupTaskResult" } } } } } } }, "/veeam/restore": { "post": { "tags": [ "VeeamTask" ], "summary": "Restores a cataloged backup (by GUID) to a new VM. Validates the backup GUID belongs to the caller's\r\ntenant before enqueuing. Returns a task id; if Wait=true blocks up to WaitTimeoutSeconds for the\r\nresult, otherwise returns immediately.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreVmRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RestoreVmRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RestoreVmRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreTaskResult" } } } } } } }, "/veeam/restore-status": { "post": { "tags": [ "VeeamTask" ], "summary": "Queries a previously queued restore task by its GUID (returned from /veeam/restore).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetVeeamTaskRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreTaskResult" } } } } } } }, "/vms/change-compute": { "post": { "tags": [ "VmCompute" ], "summary": "Changes a VM's vCPU count and memory (whole numbers; memory in whole GB).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVmComputeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChangeVmComputeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChangeVmComputeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/compute-status": { "post": { "tags": [ "VmCompute" ], "summary": "Queries a previously queued compute change by its GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/create": { "post": { "tags": [ "VmCreate" ], "summary": "Creates a new VM from an offering in a zone. Returns a task id AND the generated credentials (once);\r\nif Wait=true the call blocks up to WaitTimeoutSeconds for the clone to finish, otherwise returns\r\nimmediately. The credentials are returned either way (they're generated before the clone runs).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateVmRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateVmRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResult" } } } } } } }, "/vms/create-status": { "post": { "tags": [ "VmCreate" ], "summary": "Queries a previously queued create task by its GUID (returned from /vms/create). Never\r\n returns credentials.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmCreateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetVmCreateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetVmCreateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResult" } } } } } } }, "/vms/delete": { "post": { "tags": [ "VmDelete" ], "summary": "Soft-deletes a VM (renames it \"-deleted\" on the hypervisor and hides it).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVmRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteVmRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/DeleteVmRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/delete-status": { "post": { "tags": [ "VmDelete" ], "summary": "Queries a previously queued VM soft-delete by its GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/backups/delete": { "post": { "tags": [ "VmDelete" ], "summary": "Soft-deletes a cataloged backup (synchronous DB flag; the Veeam restore point is retained).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBackupRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteBackupRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/DeleteBackupRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeleteResult" } } } } } } }, "/vms/extend-disk": { "post": { "tags": [ "VmDisk" ], "summary": "Grows an existing disk (identified by label) to a larger total capacity.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendVmDiskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ExtendVmDiskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ExtendVmDiskRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/add-disk": { "post": { "tags": [ "VmDisk" ], "summary": "Adds a new disk. On Proxmox a target storage is required and validated; on VMware it's ignored.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddVmDiskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddVmDiskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddVmDiskRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/disk-status": { "post": { "tags": [ "VmDisk" ], "summary": "Queries a queued disk resize by GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/add-disk-status": { "post": { "tags": [ "VmDisk" ], "summary": "Queries a queued disk add by GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/change-portgroup": { "post": { "tags": [ "VmNetwork" ], "summary": "Moves an adapter (by label) onto a different network / port group (by name).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVmPortGroupRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChangeVmPortGroupRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChangeVmPortGroupRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/add-nic": { "post": { "tags": [ "VmNetwork" ], "summary": "Adds a new adapter attached to the named network.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddVmNicRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AddVmNicRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AddVmNicRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/remove-nic": { "post": { "tags": [ "VmNetwork" ], "summary": "Removes an adapter (by label) from the VM.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveVmNicRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RemoveVmNicRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RemoveVmNicRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/portgroup-status": { "post": { "tags": [ "VmNetwork" ], "summary": "Queries a queued port-group change by GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/nic-status": { "post": { "tags": [ "VmNetwork" ], "summary": "Queries a queued add/remove-adapter action by GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/change-password": { "post": { "tags": [ "VmPassword" ], "summary": "Sets a guest OS account's password. The passwords are encrypted server-side before enqueue.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVmPasswordRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChangeVmPasswordRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChangeVmPasswordRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/password-status": { "post": { "tags": [ "VmPassword" ], "summary": "Queries a queued password change by GUID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/VmTaskStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTaskResult" } } } } } } }, "/vms/change-state": { "post": { "tags": [ "VmState" ], "summary": "Changes a VM's power state (start / stop / graceful shutdown). Returns a task id; if Wait=true the\r\ncall blocks up to WaitTimeoutSeconds for the final result, otherwise it returns immediately.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVmStateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChangeVmStateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChangeVmStateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVmStateResult" } } } } } } }, "/vms/task-status": { "post": { "tags": [ "VmState" ], "summary": "Queries a previously queued task by its GUID (returned from change-state).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmStateTaskRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetVmStateTaskRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GetVmStateTaskRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVmStateTaskResult" } } } } } } } }, "components": { "schemas": { "AddVmDiskRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, unique within the tenant.", "nullable": true }, "capacityGb": { "type": "number", "description": "New disk size in GB.", "format": "double" }, "datastoreName": { "type": "string", "description": "Target storage/datastore name. Required on Proxmox; ignored on VMware.", "nullable": true }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to add a new disk to a VM. On Proxmox a target storage is required (validated against the\r\nhypervisor's datastore inventory); on VMware it's ignored (the new disk lands on the VM's home datastore)." }, "AddVmNicRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "nullable": true }, "networkName": { "type": "string", "description": "The network / port group display name to attach the new adapter to.", "nullable": true }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to add a new network adapter to a VM, attached to the named network." }, "BackupDeleteResult": { "type": "object", "properties": { "status": { "type": "string", "description": "\"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message.", "nullable": true } }, "additionalProperties": false, "description": "Result of a synchronous backup delete (a DB flag; no engine task to poll)." }, "BackupTaskResult": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The task GUID identifying this backup, if it was successfully queued (null on auth/validation failure).", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "\"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (success text, validation/auth error, or the engine's result).", "nullable": true }, "sessionId": { "type": "string", "description": "The VBR session GUID for the backup run, once known.", "nullable": true }, "backupGuid": { "type": "string", "description": "The catalog GUID for the completed backup — populated only once CS4.Cloud.ApiService.Models.BackupTaskResult.Status == \"ok\".\r\n This is the handle the caller must retain; it is the sole input that identifies what to restore.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Result of a backup request. Carries the task id to poll, and — once the backup succeeds — the\r\n durable backup GUID the caller keeps and later sends to restore." }, "BackupVmRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "description": "The API key's name (as created in the UserConsole \"API Keys\" screen).", "nullable": true }, "apiKeySecret": { "type": "string", "description": "The API key's secret (shown once at creation).", "nullable": true }, "vmName": { "type": "string", "description": "The VM to back up, by display name — the only VM identifier the caller provides.", "nullable": true }, "zoneCode": { "type": "string", "description": "Optional zone code narrowing which of the tenant's Veeam servers to search for the VM's job.\r\n Omitted ⇒ search all the tenant's enabled servers.", "nullable": true }, "wait": { "type": "boolean", "description": "When true, the API waits (up to CS4.Cloud.ApiService.Models.BackupVmRequest.WaitTimeoutSeconds) for the engine to finish and returns\r\nthe final result (including CS4.Cloud.ApiService.Models.BackupTaskResult.BackupGuid). When false (default), it returns\r\nimmediately with the task id to poll via /veeam/backup-status. A backup can run for many minutes, so\r\npolling is the usual path; the inline wait is capped low and mainly useful for short jobs." }, "waitTimeoutSeconds": { "type": "integer", "description": "Max seconds to wait when CS4.Cloud.ApiService.Models.BackupVmRequest.Wait is true. Defaulted and capped by the server.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to back up a VM. Mirrors the legacy TaskVmBackup contract (a VM name in, a backup GUID out) —\r\nthe caller never supplies a Veeam job or server; those are resolved server-side by the engine against\r\nVBR. All parameters (including credentials) travel in the body; the caller authenticates with an API\r\nkey created in the UserConsole (CS4.Cloud.ApiService.Models.BackupVmRequest.ApiKeyName + CS4.Cloud.ApiService.Models.BackupVmRequest.ApiKeySecret), which scopes the\r\noperation to that key's tenant. The tenant is never a parameter." }, "ChangeVmComputeRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, unique within the tenant.", "nullable": true }, "cpuCount": { "type": "integer", "description": "New vCPU count (whole number, ≥ 1).", "format": "int32" }, "memoryGb": { "type": "integer", "description": "New memory in whole GB (≥ 1). Converted to MB server-side.", "format": "int32" }, "wait": { "type": "boolean", "description": "When true, wait (up to CS4.Cloud.ApiService.Models.ChangeVmComputeRequest.WaitTimeoutSeconds) for the engine to finish; else return the task id immediately." }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to change a VM's vCPU count and memory. Authenticated with an API key (name + secret) that\r\nscopes the operation to its tenant. vCPU and memory are whole numbers; memory is in whole GB." }, "ChangeVmPasswordRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "nullable": true }, "guestUsername": { "type": "string", "description": "The guest OS account whose password is being set (e.g. \"administrator\", \"root\").", "nullable": true }, "oldPassword": { "type": "string", "description": "The account's current password (used as the in-guest auth credential).", "nullable": true }, "newPassword": { "type": "string", "description": "The new password to set.", "nullable": true }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to change a guest OS account's password inside a VM. Authenticated with an API key scoping to\r\nits tenant. The guest credentials travel over HTTPS to this service, which encrypts them with the\r\nshared SecretProtector before they touch the database — they are never stored or logged in plaintext.\r\nRequires VMware Tools (vSphere) / the QEMU guest agent (Proxmox) running in the guest." }, "ChangeVmPortGroupRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "nullable": true }, "nicLabel": { "type": "string", "description": "The adapter's label as shown in inventory (e.g. \"Network adapter 1\").", "nullable": true }, "networkName": { "type": "string", "description": "The target network / port group display name (must exist for this VM's hypervisor).", "nullable": true }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to move a VM's network adapter onto a different port group / network. The adapter is identified\r\nby its label (e.g. \"Network adapter 1\") and the target by its network display name — both resolved\r\nserver-side against the tenant's synced inventory. Authenticated with an API key scoping to its tenant." }, "ChangeVmStateRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "description": "The API key's name (as created in the UserConsole \"API Keys\" screen).", "nullable": true }, "apiKeySecret": { "type": "string", "description": "The API key's secret (shown once at creation).", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, as it appears in this tenant's inventory. Must be unique within the tenant.", "nullable": true }, "action": { "type": "string", "description": "The action: \"start\", \"stop\" (hard power-off), \"shutdown\" (graceful guest shutdown), or \"restart\" (hard reset).", "nullable": true }, "wait": { "type": "boolean", "description": "When true, the API waits (up to CS4.Cloud.ApiService.Models.ChangeVmStateRequest.WaitTimeoutSeconds) for the engine to finish the\r\naction and returns the final result. When false (default), it returns immediately with the task id\r\nto poll via /vms/task-status." }, "waitTimeoutSeconds": { "type": "integer", "description": "Max seconds to wait when CS4.Cloud.ApiService.Models.ChangeVmStateRequest.Wait is true. Defaulted and capped by the server.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to change a VM's power state. All parameters (including credentials) travel in the body — the\r\ncaller authenticates with an API key created in the UserConsole (CS4.Cloud.ApiService.Models.ChangeVmStateRequest.ApiKeyName +\r\nCS4.Cloud.ApiService.Models.ChangeVmStateRequest.ApiKeySecret), which scopes the operation to that key's tenant." }, "ChangeVmStateResult": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The task GUID identifying this action, if it was successfully queued (null on auth/validation failure).", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "Overall status: \"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (success text, validation/auth error, or the engine's result).", "nullable": true }, "powerState": { "type": "string", "description": "The VM's current power state when known (populated once the engine has acted / on wait).", "nullable": true } }, "additionalProperties": false, "description": "Result of a change-state request. Carries the task id so the caller can query later by GUID." }, "CreateVmRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "offeringName": { "type": "string", "description": "The offering to deploy, by name (as curated in the UserConsole \"VM Templates\" screen). The\r\n offering fixes the template + OS family + default sizing.", "nullable": true }, "zoneCode": { "type": "string", "description": "The zone whose default host/datastore place the new VM. Required.", "nullable": true }, "targetNetwork": { "type": "string", "description": "Destination network; null/empty ⇒ use the zone's default network (else the template's original).", "nullable": true }, "sshPublicKey": { "type": "string", "description": "Optional caller-supplied OpenSSH public key for a Linux offering. When set, the server injects\r\n it and returns NO private key. When null for a Linux offering, the server generates a keypair and\r\n returns the private key once. Ignored for Windows offerings.", "nullable": true }, "powerOn": { "type": "boolean", "description": "Whether to power the new VM on after creation (customization applies on first boot)." }, "wait": { "type": "boolean", "description": "When true, waits (up to CS4.Cloud.ApiService.Models.CreateVmRequest.WaitTimeoutSeconds) for the engine to finish and returns\r\n the final result; otherwise returns immediately with the task id to poll via /vms/create-status. The\r\n credentials are returned either way (they are generated at enqueue, before the clone runs)." }, "waitTimeoutSeconds": { "type": "integer", "description": "Max seconds to wait when CS4.Cloud.ApiService.Models.CreateVmRequest.Wait is true. Defaulted and capped by the server.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to create a brand-new VM from a template offering. The caller picks an OFFERING (curated in the\r\nUserConsole \"VM Templates\" screen) plus a ZONE (which supplies the target host/datastore) and an optional\r\nNETWORK — mirroring the restore contract. The new VM's name is SERVER-GENERATED (`ins-`);\r\nit is never client-supplied. All parameters travel in the body; the caller authenticates with an API key\r\n(CS4.Cloud.ApiService.Models.CreateVmRequest.ApiKeyName + CS4.Cloud.ApiService.Models.CreateVmRequest.ApiKeySecret) which scopes the operation to that key's tenant.\r\n \r\nCredentials are generated SERVER-SIDE and returned ONCE in the response (over TLS): a Windows admin\r\npassword, or — for Linux — an SSH private key. For Linux the caller may instead supply their own\r\nCS4.Cloud.ApiService.Models.CreateVmRequest.SshPublicKey, in which case the server injects it and returns no private key." }, "CreateVmResult": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "\"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "nullable": true }, "targetVmName": { "type": "string", "description": "The server-generated name of the new VM (`ins-`).", "nullable": true }, "createdVmKey": { "type": "string", "description": "The new VM's hypervisor MoRef, once the clone has produced it.", "nullable": true }, "windowsPassword": { "type": "string", "description": "The generated Windows administrator password — returned ONCE for a Windows offering. Null for\r\n Linux, or on any failure before credentials were generated.", "nullable": true }, "linuxPrivateKey": { "type": "string", "description": "The generated Linux SSH PRIVATE key (PKCS#8 PEM) — returned ONCE for a Linux offering when the\r\n server generated the keypair (i.e. the caller did not supply their own public key). Never stored.", "nullable": true }, "linuxKeyFingerprint": { "type": "string", "description": "The Linux key fingerprint (`SHA256:…`) for reference. Present for Linux offerings.", "nullable": true } }, "additionalProperties": false, "description": "Result of a create request. Carries the task id to poll, the server-generated VM name, and —\r\n ONCE, only in the create response — the generated credentials. Neither the Windows password nor the Linux\r\n private key is ever returned again by /vms/create-status." }, "DatastoreDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "nullable": true }, "hostName": { "type": "string", "description": "The host (ESXi/node) this mount entry belongs to; null if not host-scoped.", "nullable": true }, "type": { "type": "string", "description": "\"VMFS\" | \"NFS\" | … (as reported).", "nullable": true }, "capacityGb": { "type": "number", "format": "double", "nullable": true }, "freeGb": { "type": "number", "format": "double", "nullable": true }, "lastSyncedDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A datastore (one entry per host it's mounted on)." }, "DatastoreDtoInventoryListResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatastoreDto" }, "nullable": true } }, "additionalProperties": false, "description": "A list result: status/message + the items. Items is empty on failure." }, "DeleteBackupRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "backupGuid": { "type": "string", "description": "The backup's catalog GUID (as returned by a prior backup).", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request to soft-delete a cataloged backup by its GUID. Authenticated the same way. The backup drops out\r\nof the lists and can no longer be restored; the underlying Veeam restore point is left in place." }, "DeleteVmRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, unique within the tenant.", "nullable": true }, "wait": { "type": "boolean", "description": "When true, wait (up to CS4.Cloud.ApiService.Models.DeleteVmRequest.WaitTimeoutSeconds) for the engine to finish; else return the task id immediately." }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to soft-delete a VM. Authenticated with an API key (name + secret) that scopes the operation to\r\nits tenant. This does NOT remove the VM from the hypervisor: the engine renames it \"-deleted\"\r\non the hypervisor and flags the inventory row so it drops out of the tenant's lists." }, "ExtendVmDiskRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, unique within the tenant.", "nullable": true }, "diskLabel": { "type": "string", "description": "The disk's label as shown in inventory (e.g. \"Hard disk 1\").", "nullable": true }, "targetCapacityGb": { "type": "number", "description": "New total capacity in GB (must be larger than the disk's current size).", "format": "double" }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to grow an existing VM disk. Authenticated with an API key scoping to its tenant. The disk is\r\nidentified by its label (e.g. \"Hard disk 1\"), resolved to the platform key server-side. Disks are\r\ngrow-only; a target not larger than current is rejected by the hypervisor." }, "GetHypervisorRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Request to read one hypervisor by name." }, "GetNamedInventoryRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "description": "Optional hypervisor filter (by name) to disambiguate a name shared across hypervisors.", "nullable": true } }, "additionalProperties": false, "description": "Request to read one datastore/network/host by name, optionally scoped to a hypervisor (needed to\r\n disambiguate when the same name exists on more than one hypervisor)." }, "GetVeeamTaskRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "taskId": { "type": "string", "description": "The task GUID returned by /veeam/backup or /veeam/restore.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request to query a previously queued backup or restore task by its GUID. Authenticated the same way." }, "GetVmCreateRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "taskId": { "type": "string", "description": "The task GUID returned by /vms/create.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request to query a previously queued create task by its GUID. Authenticated the same way.\r\n Never returns credentials." }, "GetVmRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "description": "The VM's display name, unique within the tenant.", "nullable": true }, "syncNow": { "type": "boolean", "description": "When true, queue a live inventory refresh for this VM's hypervisor. The refresh runs on\r\n the engine (async); this call still returns the currently-cached detail with\r\n CS4.Cloud.ApiService.Models.GetVmResult.RefreshQueued set — re-call in a few seconds for the refreshed data." } }, "additionalProperties": false, "description": "Request to read one VM's detail by name. Authenticated with an API key (name + secret) that scopes the\r\nlookup to its tenant. Read-only — served from the synced inventory (dbo.vm_inventory / vm_disk_inventory\r\n/ vm_nic_inventory), not a live hypervisor round-trip." }, "GetVmResult": { "type": "object", "properties": { "status": { "type": "string", "description": "\"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (error text on failure; \"OK\" on success).", "nullable": true }, "virtualMachine": { "$ref": "#/components/schemas/VmDetailDto" }, "refreshQueued": { "type": "boolean", "description": "True when SyncNow was requested and a live refresh was queued for the engine; false when\r\n SyncNow was requested but queuing was unavailable; null when SyncNow was not requested. The returned\r\n CS4.Cloud.ApiService.Models.GetVmResult.VirtualMachine is always the currently-cached detail — re-call after a few seconds for\r\n the refreshed data.", "nullable": true }, "refreshRequestId": { "type": "integer", "description": "The queued sync request's id when CS4.Cloud.ApiService.Models.GetVmResult.RefreshQueued is true; null otherwise. Pass it\r\n to `vms/sync-status` to poll the refresh to completion — a full-hypervisor sync is asynchronous\r\n and can take ~a minute, so the detail above stays stale until the sync finishes.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Result of GetVirtualMachine: a status/message plus the VM detail (null on failure/not-found)." }, "GetVmStateTaskRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "taskId": { "type": "string", "description": "The task GUID returned by /vms/change-state.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request to query a previously queued task by its GUID. Authenticated the same way." }, "GetVmStateTaskResult": { "type": "object", "properties": { "status": { "type": "string", "description": "\"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (the engine's result, or an auth/not-found error).", "nullable": true }, "powerState": { "type": "string", "description": "The VM's current power state when known.", "nullable": true } }, "additionalProperties": false, "description": "Result of a task-status query." }, "HostDto": { "type": "object", "properties": { "hostName": { "type": "string", "nullable": true }, "vmCount": { "type": "integer", "format": "int32" }, "poweredOnCount": { "type": "integer", "format": "int32" }, "totalVcpu": { "type": "integer", "format": "int32" }, "totalMemoryMb": { "type": "integer", "format": "int64" }, "totalStorageGb": { "type": "number", "format": "double" }, "datastoreCount": { "type": "integer", "format": "int32" }, "lastSyncedDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A host (ESXi host / Proxmox node), derived from the VMs that report it (no host table exists).\r\n Fields are aggregates over that host's live VMs plus its datastore count." }, "HostDtoInventoryItemResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "item": { "$ref": "#/components/schemas/HostDto" } }, "additionalProperties": false, "description": "A single-item result: status/message + the item (null on failure/not-found)." }, "HostDtoInventoryListResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HostDto" }, "nullable": true } }, "additionalProperties": false, "description": "A list result: status/message + the items. Items is empty on failure." }, "HypervisorDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "kind": { "type": "string", "description": "\"VMware\" | \"Proxmox\".", "nullable": true }, "host": { "type": "string", "description": "The management host/endpoint (hostname or IP) — not a credential.", "nullable": true }, "port": { "type": "integer", "format": "int32" }, "isEnabled": { "type": "boolean" }, "connectionStatus": { "type": "string", "description": "\"Online\" | \"Offline\" | \"Unknown\" — last connection-health probe result.", "nullable": true }, "statusMessage": { "type": "string", "nullable": true }, "statusCheckedDate": { "type": "string", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "format": "date-time" }, "lastVmSyncDate": { "type": "string", "format": "date-time", "nullable": true }, "hostCount": { "type": "integer", "format": "int32", "nullable": true }, "vmCount": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "A hypervisor. Never carries credentials (no password, no connection username)." }, "HypervisorDtoInventoryItemResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "item": { "$ref": "#/components/schemas/HypervisorDto" } }, "additionalProperties": false, "description": "A single-item result: status/message + the item (null on failure/not-found)." }, "HypervisorDtoInventoryListResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HypervisorDto" }, "nullable": true } }, "additionalProperties": false, "description": "A list result: status/message + the items. Items is empty on failure." }, "InventoryAuthRequestBody": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "A concrete auth-only request body (for endpoints that take no other parameters, e.g. list the\r\n tenant's hypervisors). Abstract bases can't be model-bound, so this is the bindable shape." }, "InventoryListRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "description": "Optional: restrict the list to a single hypervisor (by its display name, unique per tenant).", "nullable": true }, "pageNumber": { "type": "integer", "description": "1-based page number; 25 rows per page, ordered by VM name. Omitted/<1 is treated as page 1.\r\n A page past the last returns an empty list. (Read by vms/list only.)", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "A list request with an optional hypervisor filter. When HypervisorName is null/blank the list\r\n spans all the tenant's hypervisors; otherwise it's narrowed to that one (resolved by name within the tenant)." }, "NetworkDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "nullable": true }, "networkKey": { "type": "string", "description": "Hypervisor-native moref (network-… / dvportgroup-…); null on Proxmox.", "nullable": true }, "type": { "type": "string", "description": "STANDARD_PORTGROUP | DISTRIBUTED_PORTGROUP | OPAQUE_NETWORK … (as reported).", "nullable": true }, "lastSyncedDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A network / portgroup." }, "NetworkDtoInventoryListResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkDto" }, "nullable": true } }, "additionalProperties": false, "description": "A list result: status/message + the items. Items is empty on failure." }, "RemoveVmNicRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "vmName": { "type": "string", "nullable": true }, "nicLabel": { "type": "string", "description": "The adapter's label as shown in inventory (e.g. \"Network adapter 2\").", "nullable": true }, "wait": { "type": "boolean" }, "waitTimeoutSeconds": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to remove a network adapter from a VM, identified by its label." }, "RestoreTaskResult": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "\"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "nullable": true }, "sessionId": { "type": "string", "description": "The VBR restore session GUID, once known.", "nullable": true }, "targetVmName": { "type": "string", "description": "The server-generated name of the new VM this restore creates (`vm-`).\r\n A restore never overwrites an existing VM, so this is always a fresh name.", "nullable": true } }, "additionalProperties": false, "description": "Result of a restore request. Carries the task id to poll and the VBR restore session id once known." }, "RestoreVmRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "backupGuid": { "type": "string", "description": "The backup to restore — the GUID returned by a prior successful backup.", "format": "uuid", "nullable": true }, "targetNetwork": { "type": "string", "description": "Destination network; null/empty ⇒ keep original (disconnected, matching legacy default).", "nullable": true }, "powerOn": { "type": "boolean", "description": "Whether to power the VM on after restore." }, "wait": { "type": "boolean", "description": "When true, waits (up to CS4.Cloud.ApiService.Models.RestoreVmRequest.WaitTimeoutSeconds) for the engine to start the restore\r\n and returns the result; otherwise returns immediately with the task id to poll via /veeam/restore-status." }, "waitTimeoutSeconds": { "type": "integer", "description": "Max seconds to wait when CS4.Cloud.ApiService.Models.RestoreVmRequest.Wait is true. Defaulted and capped by the server.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to restore a cataloged backup to a new VM. Mirrors the legacy TaskVmRestore contract\r\n (a backup GUID + target params). Authenticated the same way. The destination host and datastore are\r\n NOT accepted from the caller: a restore always targets the backup's zone default host/datastore (set\r\n on the UserConsole \"Location > Zone\" page), resolved by the engine at claim time\r\n (VeeamRestoreQueue.ClaimNextAsync) — the datastore falls back to the restore point's original when the\r\n zone sets none. A zone with no (single) default restore host set makes the restore fail clearly. The\r\n new VM's name is also NOT accepted from the caller: a restore always creates a NEW VM under a\r\n server-generated `vm-` name (never overwriting an existing VM), returned in\r\n CS4.Cloud.ApiService.Models.RestoreTaskResult.TargetVmName." }, "StatusRspn": { "type": "object", "properties": { "coreDatabaseStatus": { "type": "string", "nullable": true }, "vbrStatus": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Result of the GET /status health probe (ports the legacy StatusController view data)." }, "SyncStatusRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "requestId": { "type": "integer", "description": "The sync request id returned as CS4.Cloud.ApiService.Models.GetVmResult.RefreshRequestId.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request to poll a previously queued inventory refresh (the CS4.Cloud.ApiService.Models.GetVmResult.RefreshRequestId\r\nreturned from a `vms/get` call with syncNow). Authenticated with the same API key; the request is\r\nscoped to the key's tenant so one tenant can't read another's sync." }, "SyncStatusResult": { "type": "object", "properties": { "status": { "type": "string", "description": "\"ok\" | \"failed\" — the envelope status of THIS status call (bad key / unknown id → \"failed\").\r\n This is distinct from CS4.Cloud.ApiService.Models.SyncStatusResult.SyncStatus, which is the queued sync's own lifecycle state.", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (error text on failure; the sync's own message otherwise).", "nullable": true }, "syncStatus": { "type": "string", "description": "The queued sync's lifecycle state: \"pending\" | \"running\" | \"ok\" | \"failed\"; null when the\r\n status call itself failed (bad key / unknown id).", "nullable": true }, "isComplete": { "type": "boolean", "description": "True once the sync reached a terminal state (ok/failed) — i.e. the refreshed inventory is\r\n ready to re-read via vms/get. False while still pending/running; null when the call failed.", "nullable": true } }, "additionalProperties": false, "description": "Result of vms/sync-status: the queued refresh's current state." }, "VmDetailDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "description": "The owning hypervisor's display name.", "nullable": true }, "hypervisorKind": { "type": "string", "description": "\"VMware\" | \"Proxmox\".", "nullable": true }, "vmKey": { "type": "string", "description": "Hypervisor-native VM id (vCenter moref / Proxmox \"qemu/@\"), stable across syncs.", "nullable": true }, "powerState": { "type": "string", "description": "Raw power state as the hypervisor reports it (e.g. \"POWERED_ON\" / \"running\").", "nullable": true }, "cpuCount": { "type": "integer", "format": "int32", "nullable": true }, "memoryMb": { "type": "integer", "format": "int32", "nullable": true }, "storageGb": { "type": "number", "format": "double", "nullable": true }, "hostName": { "type": "string", "description": "The host (ESXi/Proxmox node) the VM runs on, if resolved at last sync.", "nullable": true }, "guestOs": { "type": "string", "description": "Guest OS as reported at last sync (raw identifier); null if not reported.", "nullable": true }, "guestOsFamily": { "type": "string", "description": "Coarse OS family: \"Windows\" | \"Linux\" | \"Other\"; null if unknown.", "nullable": true }, "lastSyncedDate": { "type": "string", "description": "UTC time this VM was last synced from the hypervisor.", "format": "date-time" }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/VmDiskDto" }, "nullable": true }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/VmNicDto" }, "nullable": true } }, "additionalProperties": false, "description": "A VM's synced detail: core fields plus its disks and network adapters." }, "VmDiskDto": { "type": "object", "properties": { "diskKey": { "type": "string", "description": "Hypervisor-native per-VM disk key (vSphere disk moref / Proxmox slot e.g. \"scsi0\").", "nullable": true }, "label": { "type": "string", "nullable": true }, "capacityGb": { "type": "number", "format": "double", "nullable": true }, "datastoreName": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "One virtual disk of a VM." }, "VmListItemDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "hypervisorName": { "type": "string", "nullable": true }, "powerState": { "type": "string", "nullable": true }, "cpuCount": { "type": "integer", "format": "int32", "nullable": true }, "memoryMb": { "type": "integer", "format": "int32", "nullable": true }, "storageGb": { "type": "number", "format": "double", "nullable": true }, "hostName": { "type": "string", "nullable": true }, "guestOs": { "type": "string", "nullable": true }, "guestOsFamily": { "type": "string", "nullable": true }, "lastSyncedDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A VM as it appears in the list (core fields). Use /vms/get for disks/NICs." }, "VmListItemDtoInventoryListResult": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VmListItemDto" }, "nullable": true } }, "additionalProperties": false, "description": "A list result: status/message + the items. Items is empty on failure." }, "VmNicDto": { "type": "object", "properties": { "nicKey": { "type": "string", "description": "Hypervisor-native per-VM NIC key (vSphere NIC moref / Proxmox slot e.g. \"net0\").", "nullable": true }, "label": { "type": "string", "nullable": true }, "macAddress": { "type": "string", "nullable": true }, "networkName": { "type": "string", "description": "The attached portgroup / network display name as resolved at last sync.", "nullable": true }, "connected": { "type": "boolean", "nullable": true }, "ipV4": { "type": "array", "items": { "type": "string" }, "description": "Guest-reported IPv4 addresses at last sync (from VMware Tools / QEMU guest agent). Empty when\r\n the guest reported none or the agent/tools weren't reporting — a NIC can carry more than one.", "nullable": true }, "ipV6": { "type": "array", "items": { "type": "string" }, "description": "Guest-reported IPv6 addresses at last sync (link-local and/or global). Empty when none were\r\n reported. A NIC commonly has several (e.g. a link-local fe80:: plus a global address).", "nullable": true } }, "additionalProperties": false, "description": "One network adapter of a VM." }, "VmTaskResult": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The task GUID identifying this action, if it was queued (null on auth/validation failure).", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "\"pending\" | \"running\" | \"ok\" | \"failed\".", "nullable": true }, "message": { "type": "string", "description": "Human-readable message (success text, validation/auth error, or the engine's result).", "nullable": true } }, "additionalProperties": false, "description": "Result of a task-queuing action: the task id to poll, plus status/message." }, "VmTaskStatusRequest": { "type": "object", "properties": { "apiKeyName": { "type": "string", "nullable": true }, "apiKeySecret": { "type": "string", "nullable": true }, "taskId": { "type": "string", "description": "The task GUID returned by the action endpoint.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request to query a previously queued VM task by its GUID. Authenticated the same way." }, "WebQueryRqst": { "type": "object", "properties": { "createTaskRqst": { "nullable": true }, "deleteImageRqst": { "nullable": true }, "deleteVirtualMachineRqst": { "nullable": true }, "getDatastoreListRqst": { "nullable": true }, "getHypervisorListRqst": { "nullable": true }, "getImageInfoRqst": { "nullable": true }, "getTaskStatusRqst": { "nullable": true }, "getVirtualMachineRqst": { "nullable": true }, "getVirtualMachinesListRqst": { "nullable": true }, "readDataEventsRqst": { "nullable": true }, "readVmResourceUsageRqst": { "nullable": true }, "readVmUsageLogRqst": { "nullable": true }, "readVmwareHostRqst": { "nullable": true }, "readWinKeyRqst": { "nullable": true }, "updateVirtualMachineConfigRqst": { "nullable": true }, "updateVirtualMachineNameRqst": { "nullable": true }, "updateVirtualMachinePasswordRqst": { "nullable": true }, "resetVirtualMachineUuidRqst": { "nullable": true }, "updateVirtualMachineDiskRqst": { "nullable": true } }, "additionalProperties": false, "description": "Request envelope for POST /WebQuery. Exactly one member is expected to be non-null; it selects\r\nwhich operation the gateway dispatches (mirrors the legacy WebQueryIO.WebQuery switch)." }, "WebQueryRspn": { "type": "object", "properties": { "createTaskRspn": { "nullable": true }, "deleteImageRspn": { "nullable": true }, "deleteVirtualMachineRspn": { "nullable": true }, "genericRspn": { "nullable": true }, "getDatastoreListRspn": { "nullable": true }, "getHypervisorListRspn": { "nullable": true }, "getImageInfoRspn": { "nullable": true }, "getTaskStatusRspn": { "nullable": true }, "getVirtualMachineRspn": { "nullable": true }, "getVirtualMachinesListRspn": { "nullable": true }, "readDataEventsRspn": { "nullable": true }, "readVmResourceUsageRspn": { "nullable": true }, "readVmUsageLogRspn": { "nullable": true }, "readVmwareHostRspn": { "nullable": true }, "readWinKeyRspn": { "nullable": true }, "updateVirtualMachineConfigRspn": { "nullable": true }, "resetVirtualMachineUuidRspn": { "nullable": true }, "updateVirtualMachineDiskRspn": { "nullable": true } }, "additionalProperties": false, "description": "Response envelope for POST /WebQuery. The populated member corresponds to the request that was\r\ndispatched (mirrors the legacy WebQueryRspn)." } } } }