Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Update mutable instance configuration
Applies a partial update to the mutable configuration of an existing Instance ("Change size" and
related editable settings surfaced by the wizard/detail UI): display name, target flavor,
monitoring agent toggle, key pair association, and user data (cloud-init). Only fields present in
the body are changed; omitted fields keep their current values. A flavor change submitted through
this endpoint behaves like a resize and may transition the instance through the RESIZE state
before returning to ACTIVE/STOPPED.
Validation: instance must exist and be visible → 404 NOT_FOUND; current status must permit
update (not BUILD/DELETING/ERROR) → 409 CONFLICT; name (when present) non-empty and unique in
the project → 422 / 409 CONFLICT; flavorId (when present) must reference an existing
flavor → 404 NOT_FOUND; userData must be valid UTF-8 text → 422 VALIDATION_FAILED.
Async & state: Conditionally asynchronous: pure metadata changes apply synchronously and
return 200 with the updated Instance; a flavor change sets status=RESIZE and the updated resource
is returned in that transitional state, emitting resource.updated SSE frames (kind=instance,
status/flavor patches) until the terminal ACTIVE or ERROR state.
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN (reader/billing roles cannot mutate); 404 NOT_FOUND
(unknown instance or referenced flavor); 409 CONFLICT (state forbids update or name collision);
412 PRECONDITION_FAILED on stale If-Match; 422 VALIDATION_FAILED; 500 INTERNAL.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. A repeated identical PATCH applies the same fields again (same end
state) and bumps version/updatedAt. Supply If-Match with the latest ETag; a mismatch returns
412 and the client must re-read before retrying. If-Match is mandatory here, so resending a
request that already succeeded with its original If-Match also gets 412.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
instanceId*stringIdentifier of the compute instance.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Partial update of mutable instance configuration; only provided fields are changed.
name?stringNew instance display name.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255flavorId?stringTarget flavor id; providing a different flavor triggers a resize workflow.
keyPairs?array<string>Rejected with VALIDATION_FAILED — the injected key set is baked into the boot's cloud-init and cannot be changed on a running server. Present on the schema so the rejection is an explicit contract rule, not a dropped unknown field.
monitoringEnabled?booleanSwitch VM metrics on/off. Switching on starts a monitoring period (metered per hour under monitoring.instance.hour), switching off ends it; re-sending the current value changes nothing. Synchronous, no provider call.
deletionProtection?booleanTurn the instance's deletion protection on/off. Synchronous; the change is programmed into Nova before it is saved: on admin-locks the server, off lifts only that lock (never a tenant suspension's). Turning it on while the instance has no Nova server yet (still building) is 409. null is rejected 422 (omit the field to leave it unchanged).
userData?string|nullUpdated Instance (possibly in transitional RESIZE state when the flavor changed).
application/json- response
Virtual machine Instance read model backing the Instances page and the instance detail page. Carries the resource scope fields (subscriptionId/projectId/region) and the timestamps (createdAt/updatedAt).
subscriptionId*stringprojectId*stringregion*RegionIdPlatform region code (a DNS-label-shaped slug, e.g. ist-1). No longer a closed enum: the set of valid region codes is operator-managed in the platform-region registry, so this carries only a shape guard. The authoritative set of activated regions is read from GET /regions; invalid-shape codes are VALIDATION_FAILED and codes absent from the registry are rejected at the resolving endpoint.
^[a-z][a-z0-9-]{1,39}$createdAt*stringupdatedAt*stringorigin?stringWhere the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.
"portal""api""system""imported"id*stringname*stringstatus*InstanceStatusLifecycle status of a compute instance (drives polling and available actions in the UI).
"BUILD""ACTIVE""STOPPED""PAUSED""SUSPENDED""RESIZE""VERIFY_RESIZE""RESCUE""ERROR""DELETING"statusReason*|Human-readable reason for the current status when it is a failure (e.g. "instance build failed on the provider" on an ERROR instance); null while the instance is healthy or the failure carried no detail. Mirrors Volume.statusReason: an ERROR row explains itself on the read model instead of forcing the console to go read the tracking Operation.
statusReasonCode*|Machine-readable companion to statusReason: a small, OPEN vocabulary of codes the console can branch on without parsing the human text, deliberately a plain string rather than a closed enum so a code the client does not recognize yet degrades to the generic failure message. Today the only value is cancelled: the resource is in its failure state because its create operation was CANCELLED; a provider object the create had already built may be left in place, and the resource's DELETE removes it. Reported only while the resource is in that failure state; null otherwise.
powerState*PowerStateHypervisor power state of the instance, shown alongside the lifecycle status.
"RUNNING""SHUTDOWN""PAUSED""CRASHED"taskState*|In-flight task indicator (e.g. powering_on, disk_attaching); null when idle.
flavor*Compute size (flavor) embedded in the Instance read model and offered by the size picker.
image*Reference to the machine image an instance was provisioned from.
fixedIp*string|nullfloatingIp*string|nullkeyPairs*array<string>Names of the SSH key pairs whose PUBLIC keys were injected into this instance at first boot via cloud-init. Empty when the instance was launched with a password only. Platform-owned: the value is recorded by the create route and is NOT re-derived from the provider (Nova's single-valued key_name is no longer used), so the collector never overwrites it.
[]passwordAuth?booleanTrue when the create provisioned an admin account with a password (adminUsername + adminPassword). The access METHOD only: neither the password nor the account name is stored or returned. Together with keyPairs it tells a client how the instance is reached -- keys only, password only, or both. Platform-owned and set once at create; false for an instance created without a password and for one adopted by discovery.
falsemonitoringEnabled*booleanWhether VM metrics are collected for customer display and billed. While true the instance's Monitoring tab serves metrics and the monitoring.instance.hour SKU is metered per hour (free unless the operator prices it); while false neither happens. Toggled with the metadata PATCH or set at create.
deletionProtection*booleanDeletion guard. While true, compute.instance.delete is refused with 409 DELETION_PROTECTED before any work starts AND the Nova server carries a platform ADMIN lock (locked_reason publiccloud:deletion-protection), so the project's own OpenStack API credentials can neither delete the server nor lift the lock; the console's start / stop / restart / resize and NIC / disk actions keep working. Turn it off with the metadata PATCH, then delete. False for every instance unless a caller turned it on; the collector never writes it.
tags*array<>securityGroups?array<string>Attached security-group ids (bound at boot and via the attach/detach actions).
[]networkInterfaces?array<>Secondary NICs attached post-boot via the interface-attach action (the primary NIC is reported via fixedIp).
[]availabilityZone?|Nova availability zone the instance runs in (OS-EXT-AZ:availability_zone, typically "nova"); null when the provider does not report it.
bootsFromVolume?booleanTrue when the instance boots from a Cinder root volume (block_device_mapping_v2) sized by the create-time osDiskGb rather than the flavor's ephemeral disk. Lets the Disks tab surface the real root volume instead of the flavor's root disk.
falserootDiskGb?|Size in GB of the boot-from-volume root volume when bootsFromVolume is true; null for an ephemeral (flavor root disk) boot or a collector-discovered instance whose root volume size is unknown.
rootVolumeName?|Display name of the standalone Cinder root volume the instance boots from (shown as 'Boot from volume ()' on the Disks tab); null for an instance whose root volume has not been adopted (e.g. a collector-discovered instance) or a legacy ephemeral instance.
rootVolumeId?|Storage read-model id of the standalone root volume the instance boots from (for deep-linking to the Volumes page); null when not adopted.
curl -X PATCH "https://example.com/scopes/string/compute/instances/string" \ -H "Content-Type: application/json" \ -d '{}'{ "subscriptionId": "string", "projectId": "string", "region": "string", "createdAt": "string", "updatedAt": "string", "origin": "portal", "id": "string", "name": "string", "status": "BUILD", "statusReason": "string", "statusReasonCode": "string", "powerState": "RUNNING", "taskState": "string", "flavor": { "id": "string", "name": "string", "family": "string", "restricted": true, "entitled": true, "vcpus": 0, "ramMb": 0, "diskGb": 0, "priceMonthly": { "amount": 0, "currency": "USD" }, "priceHourly": { "amount": 0, "currency": "USD" }, "gpu": { "count": 1, "model": "string" } }, "image": { "id": "string", "name": "string", "os": "string", "osVersion": "string" }, "fixedIp": "string", "floatingIp": "string", "keyPairs": [], "passwordAuth": false, "monitoringEnabled": true, "deletionProtection": true, "tags": [ { "key": "string", "value": "string" } ], "securityGroups": [], "networkInterfaces": [], "availabilityZone": "string", "bootsFromVolume": false, "rootDiskGb": 0, "rootVolumeName": "string", "rootVolumeId": "string"}