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.
Create (provision) a new compute instance
Provisions a new virtual machine Instance in the active scope from the instance creation wizard
submission. The backend validates the visible form constraints and cross-resource references
(region, flavor, image, optional key pair), persists the instance with status=BUILD and
powerState=SHUTDOWN, and starts the asynchronous build workflow. On acceptance the new resource
immediately becomes discoverable in the scoped instance list, and the UI polls the detail read
every 2.5s while status is in [BUILD, RESIZE, DELETING].
Validation: name must satisfy ResourceName (1–255 printable BMP characters, no
leading/trailing whitespace) and be unique within the project → 422 VALIDATION_FAILED / 409
on duplicate. The character/length rule is checked SYNCHRONOUSLY against exactly what Nova
accepts, so a name the provider would refuse never reaches it as an accepted 202 that
settles ERROR minutes later; region must be a valid RegionId enabled for the
subscription → 422; flavorId and imageId must reference existing catalog entries and
every entry of keyPairs (when provided) an existing key pair in scope → 404 NOT_FOUND; tags entries must have
non-empty keys → 422; the subscription's quota must not be exceeded by ANY dimension the
request consumes — instances, vCPUs and RAM, a floating IP when publicIp is set, and the
volume count + gigabytes of the root disk and of every dataDisks entry (each multiplied
by count for a bulk create) → 409 QUOTA_EXCEEDED, with nothing created; the selected
flavor must have capacity in the target region → 409 CAPACITY_UNAVAILABLE.
Security groups: an OMITTED (or null) securityGroupIds leaves the choice to the
provider and the project's default security group is applied; an EXPLICIT empty list
creates the instance with NO security group, which is a deliberate and different
request (matching the network-interface create's securityGroups semantics).
Async & state: Asynchronous (202). Returns the full Instance resource in its transitional
BUILD state; terminal states are ACTIVE (success, powerState=RUNNING) or ERROR (build failure).
Progress is pushed as resource.updated SSE frames with kind=instance carrying status/powerState
patches; the console invalidates its instance queries on each frame.
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN (caller is not owner/admin/contributor in scope);
404 NOT_FOUND for unknown flavorId/imageId/keyPairs reference; 409 QUOTA_EXCEEDED when subscription
limits are reached (capacity shortfalls surface on the same status as CAPACITY_UNAVAILABLE);
422 VALIDATION_FAILED for any failed field constraint; 500 INTERNAL otherwise.
Idempotency/Concurrency: Idempotency-Key is required-by-convention on this create; replaying
the same key returns the originally created Instance (same id) instead of provisioning a
duplicate. No If-Match applies to creation.
Bulk create: count > 1 provisions that many instances from ONE request under
ONE Idempotency-Key. Instances are named {name}-01 … {name}-NN; any generated name already
used by a live instance in the project → 409 CONFLICT (field=name). Acceptance is
ALL-OR-NOTHING: every check above runs once for the whole batch — the quota for N instances
(N × the flavor's vCPU/RAM) → 409 QUOTA_EXCEEDED, then placement capacity for all N → 409
CAPACITY_UNAVAILABLE with field=count and details.maxCount (how many of this flavor fit
right now; retry with a smaller count) — and a refused batch creates nothing. An accepted
batch returns InstanceBatchAccepted: one Instance + tracking Operation per instance (N
Operations, no parent). Partial success after acceptance is reported per instance: a boot
that fails settles THAT instance ERROR and ITS Operation FAILED with the reason, while the
rest proceed. A same-key retry replays the recorded batch body and provisions nothing new,
whatever state the instances have reached. count > 1 cannot be combined with
bootSource=volume or with a nics entry that reuses a portId or pins a fixedIp (one
existing volume/port/address cannot back several instances) → 422 VALIDATION_FAILED
(field=count). A flavor whose demand cannot be counted N times over — passthrough devices
(pci_passthrough:alias) or a Placement resource class the region reports no inventory for —
refuses count > 1 with 422 VALIDATION_FAILED (field=count,
details.reason=bulk_create_not_supported_for_flavor); single creates of it are unaffected.
Batches of one subscription are serialized, so two batches cannot jointly overshoot the
quota; the quota check is still not a reservation against SINGLE creates, so a single create
racing a batch may overshoot the limit by at most that one instance (the provider quota then
fails it asynchronously). Omitted count (or 1) is the
single-instance create, unchanged: the 202 body is the Instance itself.
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.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Payload for creating an instance (the instance creation wizard submission).
name*stringInstance display name; unique within the project. With count > 1 it is the name PREFIX: instances are named {name}-01 … {name}-NN (so it may be at most 252 characters).
^[^\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 <= 255count?integerNumber of instances to create from this one request (1–20, mirroring CreateDedicatedHostInput's namePrefix + quantity shape). Omitted means 1 — the single-instance create. Greater than 1 is a bulk create: accepted all-or-nothing (quota and capacity are checked for the whole batch), answered with InstanceBatchAccepted.
1 <= value <= 20region*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}$flavorId*stringbootSource?stringWhere the instance's root disk comes from (Horizon parity). "image" (default, current behaviour) creates a fresh root volume from imageId. "volume" boots an EXISTING available bootable volume (sourceVolumeId) as the root disk — no new root volume is created. "snapshot" creates a fresh root volume from a volume snapshot (sourceSnapshotId), sized by osDiskGb (>= the snapshot's size).
"image""image""volume""snapshot"imageId?|Glance image id the root volume is created from. REQUIRED when bootSource is "image" (the default); ignored/null for the "volume" and "snapshot" boot sources.
sourceVolumeId?|Contract id of an EXISTING bootable, AVAILABLE volume to boot from as the root disk. REQUIRED when bootSource is "volume" (else null). The volume becomes the instance's root volume (IN_USE at /dev/vda, delete_on_termination=false); no new root volume is created and its size is taken from the volume (osDiskGb is ignored).
sourceSnapshotId?|Contract id of an AVAILABLE snapshot the fresh root volume is created from — either a storage VOLUME snapshot or a compute VM snapshot (the id is resolved against both read models; a VM snapshot boots from the Cinder snapshot embedded in its captured Glance image). REQUIRED when bootSource is "snapshot" (else null). The root volume is sized by osDiskGb, which must be at least the snapshot's size (a VM snapshot's captured root size is additionally enforced provider-side, so the boot never truncates the disk).
osDiskGb?|Optional root (OS) disk size in GB. When provided the instance boots from a Cinder volume of this size (block_device_mapping_v2), so the root disk is no longer constrained by the flavor's ephemeral disk; must be at least the image's min-disk (bootSource "image") or the snapshot's size (bootSource "snapshot"). Ignored for bootSource "volume" (the size comes from the volume). Omitted/null boots ephemeral on the flavor's root disk (current behavior).
1 <= valuekeyPairs?array<string>Names of the SSH key pairs whose PUBLIC keys are injected at first boot. Each name must resolve to a key pair in the caller's scope (404 NOT_FOUND otherwise). The platform writes them into the boot's cloud-init ssh_authorized_keys — Nova's single-valued key_name is not used, so several keys may be selected. May be combined freely with adminUsername/adminPassword; at least one of the two authentication routes should be present or the instance has no way in.
items <= 10[]adminUsername?|Name of an administrator account to set up on the first boot, with sudo access and SSH password login turned on. Give it together with adminPassword, or neither (VALIDATION_FAILED otherwise). Omit both to sign in with SSH keys only.
^[a-z_][a-z0-9_-]{0,31}$adminPassword?|Password of the adminUsername account. The account is set up on the first boot, and SSH password login is turned on. Give both fields or neither. It takes effect only on images that support account setup on the first boot. Write-only: no response returns it.
^[^\r\n]+$8 <= length <= 72monitoringEnabled?booleanEnable VM metrics from the start. Metered under the monitoring.instance.hour SKU for as long as it stays on; free while the SKU has no price.
falseuserData?|Optional cloud-init user data executed on first boot.
tags?array<>items <= 50[]networkId?|Optional Neutron network the primary port is placed on; omitted/null attaches to the region's default tenant network. Selecting an EXTERNAL network requires an admin grant with the attach (access_as_shared) capability for the scope. Mutually exclusive with nics (supply one or the other, never both).
nics?array<>Optional ordered list of network interfaces to attach at boot (Horizon parity: multiple networks and/or existing ports). Each entry sets EXACTLY ONE of networkId (a fresh port is auto-created on that network, with the same external/allow_attach gating as the top-level networkId) or portId (an existing, unattached network-interface/port is reused). Interfaces attach in list order (the first is the primary NIC). Mutually exclusive with the top-level networkId field. Omitted keeps the single-NIC behaviour driven by networkId / the region default.
1 <= itemssecurityGroupIds?array<string>Security-group ids to bind to the instance's network interfaces at boot. OMITTED (or null) leaves the choice to the provider, which applies the project's default security group, as the OpenStack CLI / Horizon do; an explicit EMPTY LIST creates the instance with NO security group at all. The two are deliberately different requests and are NOT interchangeable — the same rule the network-interface (port) create follows for its securityGroups field.
publicIp?booleanWhen true, allocate a new public (floating) IP from the region's external pool and associate it to the instance once it is ACTIVE (Public IP: Create new, Standard/static). Association failures are non-fatal: the instance still SUCCEEDS, only without a public IP. Omitted/false leaves the instance with its fixed (private) IP only.
falsedataDisks?array<>Optional additional data disks (wizard Disks step). Each is created as a blank Cinder volume and attached once the instance is ACTIVE, in list order. Per-disk failures are non-fatal to the create (the instance still SUCCEEDS); a volume that was created but could not attach is still adopted as an AVAILABLE storage volume so it is never orphaned. Omitted/empty creates no data disks.
items <= 8[]addons?array<>Optional add-ons (catalog) to attach at create. Each selection is an add-on id from GET /catalog/addons and one of that add-on's sellable periods. The price is FROZEN at attach and metered through the billing engine (hourly add-ons accrue per running hour; month/year recur).
[]licenses?array<>Optional software licenses (catalog) to attach at create, same shape as addons but resolved against GET /catalog/licenses.
[]Creation accepted. A single-instance create (count omitted or 1) returns the Instance in its transitional BUILD state; a bulk create (count > 1) returns InstanceBatchAccepted.
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 POST "https://example.com/scopes/string/compute/instances" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "region": "string", "flavorId": "string" }'{ "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"}