Instances
All operations require authentication.
List instancesProduction
List instances
Lists all instances in the project. Each item is a full instance envelope with the same shape as the GET route (desired targetSpec and observed currentState).
Filesystem attachments
For performance, currentState.shares is not populated in list responses. To see the filesystems attached to a given instance, call GET .../instance/{instanceId} on it.
Filters
The optional name, flavor, region and status query parameters narrow the list. Each one can be repeated, for example ?status=READY&status=CREATING: repeated values of the same parameter are combined with OR, and different parameters are combined with AND. Filters apply only within the instances you are authorized to list. An unknown status value or an unavailable region is rejected with a 400 InvalidParameter.
Path parameters
Project ID
Query parameters
Filter by flavor ID or flavor name. Repeatable.
Filter by instance name (case-insensitive substring match). Repeatable.
Filter by instance region. An unavailable region is rejected. Repeatable.
Filter by resourceStatus. Repeatable.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGHeaders
Pagination cursor
Pagination size
Response
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses projectId = string
$ curl https:/[ { "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": null, "mac": null, "type": null, "version": null } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z" }]
Get an instanceProduction
Get an instance
Returns a single Public Cloud instance, including its desired targetSpec and observed currentState.
Optimistic concurrency
The checksum returned here is the hash of the current targetSpec. Keep it and send it back on any subsequent PUT or imperative action call on the instance to guard against lost updates. It is optional, but omitting it forces the write (see the PUT route).
Filesystem attachments
currentState.shares — the list of filesystems (Manila shares) attached to the instance — is populated only on this single-instance GET. It is deliberately not returned by the LIST route for performance reasons. Fetch the individual instance when you need it.
Path parameters
Instance ID
Project ID
Response
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses instanceId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": "192.0.2.0", "mac": "00:00:5e:00:53:01", "type": "ADDITIONAL", "version": 0 } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}
List compatible flavorsProduction
Compatible flavors
Returns the list of flavors this instance can be resized to. The list is computed from the instance's current flavor and the catalog of flavors available in the instance's region.
The following rules apply to the returned list:
- It excludes the instance's current flavor.
- It includes only flavors whose disk size is greater than or equal to the current flavor's disk size (a resize cannot shrink the root disk).
- It includes only flavors in the same region as the instance.
- It includes only flavors whose plan is available in the instance's region.
- It is empty for baremetal instances, which cannot be resized.
Each item has the same shape as an entry from the flavor reference catalog (publicCloud.reference.instance.Flavor). Its location.regionActivated is true, since the instance's region is activated on the project. location.availabilityZones lists the availability zones of the region, for example eu-west-par-a, eu-west-par-b and eu-west-par-c, and is empty for a single-AZ region.
Path parameters
Instance ID
Project ID
Headers
Pagination cursor
Pagination size
Response
Network bandwidth an instance of the flavor gets in Mbit/s
Free-form description of the flavor as reported by the backend. Null when no description is advertised for this flavor.
Size of the flavor's root disk in GB. This is the primary system disk provisioned for instances created from this flavor.
Size of the flavor's ephemeral disk in GB. Ephemeral storage is transient. Its contents do not survive a rebuild or deletion of the instance. Zero when the flavor provides no ephemeral disk.
Number of physical GPUs provided by the flavor. Zero for flavors without GPU.
Identifier. The OpenStack/Nova flavor ID. Stable within a region and used to reference the flavor when creating an instance.
Public availability. Whether the flavor is publicly available to the project. Private flavors are only visible to the projects they have been explicitly shared with.
Location. Region where this flavor is offered. The flavor catalog is per-region: a flavor returned for one region is not guaranteed to exist, or to carry the same characteristics, in another. regionActivated tells whether the region is already activated on the project. When false, the region must be activated on the project before use. availabilityZones lists the availability zones of the region, empty for a single-AZ region.
The backend flavor name, for example b2-7, c2-15. This is the commercial/technical name used to identify the sizing in the catalog.
RAM in MB. Amount of memory provided by the flavor, expressed in MB.
Size of the flavor's swap space in MB. Zero when the flavor provides no swap.
vCPUs. Number of virtual CPUs provided by the flavor.
Example uses instanceId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/[ { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "description": "string", "disk": 0, "ephemeral": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "isPublic": true, "location": { "availabilityZones": [ "string" ], "region": "string", "regionActivated": true }, "name": "string", "ram": 0, "swap": 0, "vcpus": 0 }]
Create an instanceProduction
Create an instance
Provisions a new instance from the supplied targetSpec. Creation is asynchronous: the resource starts in CREATING and becomes READY once the backend has booted it. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.
Create-time-only fields (immutable afterward)
Several fields can be set only at creation and can never be changed later:
location— the region (and optional availability zone) the instance is deployed in.sshKeyName— the SSH key injected into the instance at boot.group— placement / instance-group membership. It binds the instance to an existing instance group (Nova server group) forAFFINITY/ANTI_AFFINITYscheduling. Server-group membership is fixed by OpenStack at boot and cannot be added, removed, or changed afterward — there is no groupPUT.
User data (cloud-init)
targetSpec.userData is a base64-encoded (strict standard encoding) cloud-init payload handed to the instance at boot through the OpenStack metadata service / config drive, and interpreted by cloud-init inside the guest image. The encoded string must be at most 65535 bytes. It is write-only: the value is never returned by GET/LIST. It is also not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service. Only a non-reversible fingerprint of the value is retained, for change detection. Unlike the create-time-only fields above, userData can be changed later via PUT. See the PUT route for the destructive semantics of doing so.
Declarative volumes
targetSpec.volumes is a declarative list of block-volume references attached to the instance. Supply the volumes to attach at boot. On a subsequent PUT the list is diffed to attach or detach volumes (see the PUT route). There is no imperative attach/detach endpoint.
Declarative shares
targetSpec.shares is a declarative list of filesystem (Manila share) attachments. Each entry references a share plus an optional per-entry accessLevel (defaults to READ_WRITE). At creation, each attach creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network. As with volumes, the list is reconciled by diffing on PUT.
Declarative networks and public IPs
targetSpec.networks is a declarative list of network interfaces. Each entry is {id?, subnetId?, ip?, autoAssignPublicIp?}, and the fields you set decide what it means:
{"autoAssignPublicIp": true}— a public (Ext-Net) interface with a platform-assigned public IP. At most one entry may set it.{"ip": "..."}without a networkid— a public IP the project already owns: either an existing additional IP (also known as a failover IP), or an Ext-Net IP of the project in the instance's region. Any other address is rejected. Such an entry implicitly attaches the public (Ext-Net) interface. Several are allowed, and they may coexist with anautoAssignPublicIpentry.{"id": "...", "subnetId": "..."}— a private interface whose fixed address is assigned by IPAM.{"id": "...", "subnetId": "...", "ip": "..."}— a private interface whereippins the fixed address when it falls inside the subnet CIDR, and otherwise designates an existing floating IP to associate with that interface (the floating IP must already exist).
Any entry that sets autoAssignPublicIp or carries a public ip requires the optional instance/usePublicIP IAM action, including floating IP associations.
In currentState.networks the shape is different: there is one entry per network plus at most one id-less entry for the public (Ext-Net) interface, and every address is reported through that entry's addresses list. There is no scalar ip. Each address carries a type: FIXED for an address configured on the interface itself (a private fixed address, whether IPAM-assigned or pinned, and the Ext-Net address), FLOATING for a floating IP associated with the interface, and ADDITIONAL for an additional IP routed to the public interface (additional IPs no longer form their own entry). autoAssignPublicIp is never echoed back, because the backend cannot distinguish a platform-assigned address from a pinned one.
Path parameters
Project ID
Request body (required)
Desired specification. Full target specification of the instance to create. See InstanceTargetSpec for the per-field creation rules and immutability constraints.
Response
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": "192.0.2.0", "mac": "00:00:5e:00:53:01", "type": "ADDITIONAL", "version": 0 } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}
Run an instance actionProduction
Perform an instance action
Imperative endpoint for power and lifecycle actions on an instance. This is the one place such imperative operations live. Distinct from the declarative PUT on the instance, which reconciles desired state from a targetSpec diff. Actions are asynchronous: the instance transitions through the relevant transient state and the response echoes the instance. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.
Action type
The type field selects the operation:
REBOOT— reboot the instance (parameters.hardchooses a hard vs. soft reboot).START/STOP— power the instance on / off.SHELVE/UNSHELVE— shelve the instance (freeing hypervisor resources) and restore it.PAUSE/UNPAUSE— freeze a running instance in the memory of the host, and unfreeze it.SUSPEND/RESUME— save the memory state of a running instance to disk and stop it, and restore it.RESCUE/UNRESCUE— boot into rescue mode (optionally fromparameters.imageId) and return to normal boot.LOCK/UNLOCK— lock the instance against accidental actions / modifications, and unlock it.
Optimistic concurrency (checksum)
The checksum is optional. When you send it, it must match the current server-side value or the action is rejected with a checksum-mismatch error. Re-GET and retry. When you omit it (or send an empty string), the check is skipped and the action is forced (last-write-wins). An action requested while the instance is in an incompatible state is rejected with ResourceInInvalidState.
Path parameters
Instance ID
Project ID
Request body (required)
Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the action is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the action is forced (last-write-wins).
Optional parameters refining the requested action (see InstanceActionParameters). Only relevant for actions that accept options, such as a hard REBOOT or a RESCUE with a specific image. Omit for actions that take none.
Action type. The imperative action to perform on the instance (see InstanceActionTypeEnum: LOCK, UNLOCK, REBOOT, RESCUE, UNRESCUE, STOP, START, SHELVE, UNSHELVE, PAUSE, UNPAUSE, SUSPEND, RESUME).
LOCKPAUSEREBOOTRESCUERESUMESHELVESTARTSTOPSUSPENDUNLOCKUNPAUSEUNRESCUEUNSHELVEResponse
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses instanceId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": "192.0.2.0", "mac": "00:00:5e:00:53:01", "type": "ADDITIONAL", "version": 0 } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}
Delete an instanceProduction
Delete an instance
Permanently deletes a Public Cloud instance. Deletion is asynchronous: the resource transitions to DELETING, the response echoes the instance, and the backend then removes it. Poll GET .../instance/{instanceId} until it returns InstanceDoesNotExist (404) to confirm removal.
Behavior
- Independent block volumes attached to the instance are detached, not deleted — they are separate resources and survive.
- Filesystem (share) attachments are released as part of the teardown.
A delete already in progress is reported as ResourceAlreadyBeingDeleted. An instance in a transient or otherwise invalid state may be rejected with ResourceInInvalidState.
Path parameters
Instance ID
Project ID
Response
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses instanceId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": "192.0.2.0", "mac": "00:00:5e:00:53:01", "type": "ADDITIONAL", "version": 0 } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}
Update an instanceProduction
Update an instance
This is the single, declarative route for changing an instance. You do not call verb-specific endpoints. Instead you submit a new desired targetSpec and the API derives the operations to perform from the diff against the current specification. (Imperative power/lifecycle operations such as reboot, start, stop, and rescue live on the separate .../instance/{instanceId}/action route.)
Asynchronous, desired-state model
- You send the new
targetSpec, optionally together with thechecksumfrom your lastGET. - If accepted, you immediately get back the instance with the updated
targetSpecand a newchecksum.resourceStatusbecomesUPDATING. - One or more asynchronous tasks reconcile
currentStatetowardtargetSpec. PollGET .../instance/{instanceId}untilresourceStatusisREADYandcurrentTasksis empty to know the change has been applied.
Operations derived from the diff
- Rename — changing
namerenames the instance. - Resize (flavor) — changing
flavormigrates the instance to the new flavor. - Volume attach / detach — done declaratively by diffing the
volumeslist: adding a volume reference attaches that volume, removing one detaches it. There is no imperative attach/detach endpoint — the diff is the only mechanism. - Network attach / detach — done declaratively by diffing the
networkslist, whose entries are{id?, subnetId?, ip?, autoAssignPublicIp?}: a platform-assigned Ext-Net IP ({"autoAssignPublicIp": true}, at most one entry), a public IP the project already owns — additional IP or project Ext-Net IP in the instance's region — ({"ip"}, no networkid), a private interface with an IPAM address ({"id", "subnetId"}), or a private interface withipeither pinning its fixed address (address inside the subnet CIDR) or associating an existing floating IP (address outside it). Any entry that setsautoAssignPublicIpor carries a publiciprequires the optionalinstance/usePublicIPIAM action. - Filesystem (share) attach / detach — done declaratively by diffing the
shareslist. Adding an entry attaches the share: it creates a Manila IP access rule for the instance's interface on the share's network, so the instance must already have an interface on that network or the attach errors. Removing an entry detaches the share: the matching access rule is removed, and the detach is idempotent. Each entry'saccessLeveldefaults toREAD_WRITE. Caveat: managing per-share access rules directly on the share resource and attaching the same share instance-side here is unsupported — the share will reportOUT_OF_SYNC.
Immutable fields (excluded from update)
location, sshKeyName, and group are set only at creation and are not part of the update. In particular, placement-group (group) membership cannot change post-create. OpenStack/Nova server groups are immutable and there is deliberately no group PUT.
Destructive update (userData)
Changing targetSpec.userData reinstalls the instance — a Nova rebuild on its current image — which wipes the root disk and all data on it. Semantics are tri-state: omitting the field (or sending null) keeps the current value unchanged, an empty string "" clears it, and any other value replaces it. Both the clear and the replace trigger the reinstall. An instance with no image (boot-from-volume) has nothing to rebuild onto, so a userData change on it is rejected with a 400 InvalidParameter.
Optimistic concurrency (checksum)
The checksum guards against lost updates and is optional. When you send it, it must match the server-side value: if another request modified the instance since your last GET, the checksum no longer matches and the request is rejected with a checksum-mismatch error (ChecksumMismatch). Re-GET the instance and retry against the fresh state. When you omit it (or send an empty string), the check is skipped and the update is forced (last-write-wins).
Path parameters
Instance ID
Project ID
Request body (required)
Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the update is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the update is forced (last-write-wins).
Desired specification (mutable fields). Updated target specification restricted to the fields that can change after creation. Immutable fields (location, sshKeyName, placement group) are intentionally absent. See InstanceUpdateTargetSpec. userData is write-only (never echoed back) and follows tri-state semantics. Changing it (clearing or replacing) reinstalls the instance.
Response
Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins).
Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp
Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet.
In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied.
Unique identifier of the instance
Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGDesired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach).
Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp
Example uses instanceId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "availableActions": [ { "available": true, "name": "LOCK" } ], "flavor": { "bandwidth": { "private": 0, "publicInbound": 0, "publicOutbound": 0 }, "disk": 0, "gpus": 0, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "ram": 0, "vcpus": 0 }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "hostId": "string", "image": { "defaultUser": "string", "deprecated": true, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0, "status": "ACTIVE" }, "location": { "availabilityZone": "string", "region": "string" }, "locked": true, "name": "string", "networks": [ { "addresses": [ { "ip": "192.0.2.0", "mac": "00:00:5e:00:53:01", "type": "ADDITIONAL", "version": 0 } ], "gatewayId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "projectId": "string", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "accessTo": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "ACTIVE" } ], "sshKeyName": "string", "userId": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "string", "size": 0 } ] }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "flavor": { "id": "00000000-0000-0000-0000-000000000000" }, "group": { "id": "00000000-0000-0000-0000-000000000000" }, "image": { "id": "00000000-0000-0000-0000-000000000000" }, "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "networks": [ { "autoAssignPublicIp": true, "id": "00000000-0000-0000-0000-000000000000", "ip": "192.0.2.0", "subnetId": "00000000-0000-0000-0000-000000000000" } ], "powerState": "ACTIVE", "securityGroups": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "shares": [ { "accessLevel": "READ_ONLY", "id": "00000000-0000-0000-0000-000000000000" } ], "sshKeyName": "string", "volumes": [ { "id": "00000000-0000-0000-0000-000000000000" } ] }, "updatedAt": "2024-01-01T12:00:00Z"}