nova — REST API

REST API — nova — branch stable/2026.2

Branch stable/2026.2 @ 8df1922926dd (34.0.0 + 7 commits) — repository https://opendev.org/openstack/nova — analysed on 2026-10-28

Scope of this file: the compute API (nova-api, paste app osapi_compute). The metadata API (nova-metadata-api) is summarised in § 9. The flavor, extra-spec and flavor-access endpoints are specified in depth in the flavors-scoped spec (01-flavors-api_stable-2026.2.md); this file only lists them.

Related files: errors · interactions · scenarios · async processing · summary.

1. How the API is built

1.1 Request pipeline

etc/nova/api-paste.ini mounts the compute API under /v2.1 (and a legacy-v2 compatibility pipeline under /v2). For /v2.1/+ the pipeline is, outermost first (etc/nova/api-paste.ini:31-33):

Because authtoken sits inside faultwrap and sizelimit, an oversize body yields 413 before authentication, and an invalid token yields 401 before routing (so an unknown path with a bad token is a 401, not a 404).

1.2 Routing and actions

• Routes are a static list of (path, {method: [controller_factory, 'method']}) tuples, nova/api/openstack/compute/routes.py (ROUTE_LIST). Each controller factory wraps one main controller and, for /servers, 25+ extension controllers that only contribute body actions (nova/api/openstack/compute/routes.py:251).
• POST …/action routes dispatch on the single top-level key of the JSON body (nova/api/openstack/wsgi.py:347 action_peek): more than one key → 400 "too many body keys"; an unknown key → 400 "There is no such action: %s" (nova/api/openstack/wsgi.py:538).
• A project id in the URL (/v2.1/{project_id}/servers) is optional; when present it must equal the token's project, otherwise 400 "Malformed request URL" (nova/api/openstack/wsgi.py:566-572).

1.3 Microversions

• Supported range: 2.1 … 2.104 (nova/api/openstack/api_version_request.py:299-300). Without a header the request runs at the minimum 2.1 (DEFAULT_API_VERSION, nova/api/openstack/api_version_request.py:301); latest means 2.104. A version outside the range yields 406 InvalidGlobalAPIVersion (nova/api/openstack/wsgi.py:168-174).
• Headers read: OpenStack-API-Version: compute 2.x and legacy X-OpenStack-Nova-API-Version: 2.x. Responses echo both, plus Vary (nova/api/openstack/wsgi.py:609-615).
• Per-method bounds come from @wsgi.api_version(min, max) (nova/api/openstack/wsgi.py:698). Calling a method outside its range raises VersionNotFoundForAPIMethod, which the resource turns into a bare 404 "as if the method did not exist" (nova/api/openstack/wsgi.py:658-667).
• Request body schemas (@validation.schema), query schemas (@validation.query_schema) and response body schemas (@validation.response_body_schema) are all microversion-ranged and are listed per handler in _rewrite/schema-selection_stable-2026.2.json and in _rewrite/api-operations_stable-2026.2.json. Schema ranges must be contiguous: the Schemas container asserts it at import time (nova/api/validation/__init__.py:122-137).
• Success codes can be microversion-dependent (@wsgi.response(code, min, max), nova/api/openstack/wsgi.py:222-260); e.g. POST /os-keypairs returns 200 up to 2.1 and 201 from 2.2.
• Removed APIs (@wsgi.removed, nova/api/openstack/wsgi.py:685) keep their routes and answer 410 Gone at every microversion (54 operations: cells v1, nova-network proxies, agents, certificates, cloudpipe, fping, fixed IPs, floating IP DNS/bulk, virtual interfaces, security group default rules, consoles, os-getRDPConsole, resetNetwork…).
• Proxy APIs to Neutron, Glance, Cinder and Ironic (/os-networks, /os-security-groups, /os-floating-ips, /images, /os-volumes, /os-snapshots, /os-baremetal-nodes, /os-hosts…) are capped at 2.35 (2.38 for image metadata, 2.42 for /os-hosts) and then 404 (nova/api/openstack/api_version_request.py:305-311).
• /os-volumes_boot is a legacy alias of /servers, capped at 2.102.

1.4 Validation, policy, errors

• JSON-schema failures yield 400 with the jsonschema message (nova/api/validation/validators.py). Query-parameter schemas reject unknown parameters only for some APIs and microversions (additionalProperties in each query schema).
• Policies (oslo.policy, 214 default rules, nova/policies/) are checked in the handler with context.can(rule, target); a refusal raises exception.Forbidden → 403 (nova/api/openstack/wsgi.py:383-385). Default rules are scoped with enforce_scope/enforce_new_defaults personas (admin, project member, project reader, service).
• @wsgi.expected_errors(codes) (nova/api/openstack/wsgi.py:738) lets through webob HTTP errors whose code is listed, plus Forbidden, ValidationError, Unauthorized, and converts NotSupported to 400; anything else becomes 500 "Unexpected API Error" and is logged with "Unexpected exception in API method" (nova/api/openstack/wsgi.py:806-813).
• Error body: {"<faultName>": {"code": <status>, "message": "<explanation>"}}, with fault names badRequest, unauthorized, forbidden, itemNotFound, badMethod, conflictingRequest, overLimit (413/429, with retryAfter), badMediaType, notImplemented, serviceUnavailable, otherwise computeFault (nova/api/openstack/wsgi.py:876-920). See 02-errors § 1.
• Instance-state preconditions are enforced in nova/compute/api.py by decorators: check_instance_state(vm_state=…, task_state=(None,), must_have_launched=True) (nova/compute/api.py:142) — **the default requires task_state to be None, i.e. no operation in progress, and the server to have been launched once** —, reject_instance_state (nova/compute/api.py:187), check_instance_host (nova/compute/api.py:216, 409 if the server has no host; 503 if check_is_up and the source compute is down), check_instance_lock (nova/compute/api.py:247, 409 InstanceIsLocked unless admin). The handlers translate InstanceInvalidState into 409 "Cannot '<action>' instance <id> while it is in <attr> <state>" (nova/api/openstack/common.py:330-346).

1.5 Server status shown to clients

The API never exposes vm_state/task_state directly in status: it maps them through _STATE_MAP (nova/api/openstack/common.py:44, nova/api/openstack/common.py:114 status_from_state). Examples: building → BUILD; active + rebooting → REBOOT; active + rebooting_hard → HARD_REBOOT; active + resize_prep → RESIZE; resized → VERIFY_RESIZE; active + migrating → MIGRATING; stopped → SHUTOFF; soft-delete → SOFT_DELETED; shelved_offloaded → SHELVED_OFFLOADED; error → ERROR. Raw states are visible to admins as OS-EXT-STS:vm_state / OS-EXT-STS:task_state.

1.6 Where an instance lives (cells v2)

Every server lookup (common.get_instance, nova/api/openstack/common.py:463) goes through compute.API.get (nova/compute/api.py:3054): it reads instance_mappings in the API database to find the cell, then reads the cell database; before scheduling has finished, the instance only exists as a build_requests row and is served from there. A missing mapping or row is a 404. From 2.69 list/show can return a partial "down cell" record (status: UNKNOWN) when a cell database is unreachable (nova/api/openstack/compute/servers.py:169 _is_cell_down_supported).

2. Operation table

265 operations: 201 method/path routes plus 64 body actions (41 on /servers/{id}/action, of which 2 removed — the 39 live ones are in § 4 —, and 23 on /os-volumes_boot/{id}/action, flavors, aggregates, networks, fixed IPs, bare-metal nodes and migrations). 211 are live and 54 answer 410. "Microversions" is the @wsgi.api_version range of the handler (all = 2.1–2.104); "Expected errors" is the @wsgi.expected_errors list (other exceptions become 500). Handler references point at the def line. The same data, with schemas, is in _rewrite/api-operations_stable-2026.2.json.

3. Functional descriptions

3.1 POST /servers — create one or several servers

• Purpose: boot one or more virtual machines from an image or a volume, on a flavor, attached to networks.
• Actor: project member (os_compute_api:servers:create); extra rules apply to optional features: create:forced_host (target host/node in availability_zone, admin), compute:servers:create:requested_destination (host/hypervisor_hostname from 2.74, admin), create:attach_volume, create:attach_network, create:trusted_certs, create:zero_disk_flavor, network:attach_external_network (nova/api/openstack/compute/servers.py:778-797).
• Preconditions: the flavor exists and is not disabled; the image is active (or a bootable volume is given); the key pair exists; networks/ports exist and are usable; quotas allow min_count instances (nova/compute/api.py:1441); when a server group is given in os:scheduler_hints.group, its member quota allows the new members (nova/compute/api.py:1570-1583).
• Business rules:
  • min_count ≤ max_count, default min_count = 1 and max_count = min_count (nova/api/openstack/compute/servers.py:758-762); quotas may lower the number actually built down to min_count (nova/compute/api.py:1441).
  • availability_zone may carry zone:host:node to force a host (admin) (nova/compute/api.py:655 parse_availability_zone).
  • Image/flavor compatibility (min disk/RAM, zero-disk flavors, NUMA/PCI/CPU-policy extra specs) is checked by _validate_flavor_image (nova/compute/api.py:723) and _checks_for_create_and_rebuild (nova/compute/api.py:1077); metadata and injected-file quotas by nova/compute/api.py:480 and nova/compute/api.py:531.
  • Block device mappings are merged from the image, the flavor and the request, then validated (boot index, sizes, volume AZ, volume type, local disk limit) (nova/compute/api.py:1977 _validate_bdm); volumes must be in the instance AZ unless [cinder]/cross_az_attach is true (nova/compute/api.py:1331).
  • Port resource requests (QoS minimum bandwidth/packet rate) are read from Neutron and stored in the RequestSpec (nova/compute/api.py:1184).
  • Server names are stripped of surrounding blanks (nova/api/openstack/common.py:474); hostname (2.90+) and description (2.19+) are optional.
• Flow:
  1. (synchronous, nova-api) schema validation per microversion, policies, parsing of networks/BDMs/hints (nova/api/openstack/compute/servers.py:717-861).
  2. (synchronous) compute.API.create → _create_instance (nova/compute/api.py:1707): image GET from Glance, port/network checks in Neutron, volume GETs in Cinder, quota checks (legacy DB counting or Keystone unified limits, nova/compute/api.py:1408).
  3. (synchronous) for each instance: a request_specs, a build_requests and an instance_mappings row (with cell_id NULL) are inserted in one API-database transaction (nova/compute/api.py:1256, nova/compute/api.py:1540-1567); server-group membership is recorded (nova/compute/api.py:1585).
  4. (synchronous) RPC cast schedule_and_build_instances to nova-conductor (nova/compute/api.py:1836), then 202 with the server id, links and adminPass (if [api]/enable_instance_password) and a Location header (nova/api/openstack/compute/servers.py:913-923). With return_reservation_id the response is only {"reservation_id": …}.
  5. (asynchronous) conductor asks the scheduler for hosts (Placement allocation candidates + filters/weighers), claims allocations in Placement, creates the instance in the chosen cell DB, deletes the build request, and casts build_and_run_instance to the compute host. See 05-async-processing and 04-scenarios § 1.
  6. (asynchronous, nova-compute) ports bound in Neutron, volumes attached in Cinder, image fetched, guest spawned, waits for network-vif-plugged from Neutron, then vm_state=active.
• Outcome: status: BUILD in the response; final ACTIVE, or ERROR with a fault (no valid host: instance lands in cell0 with vm_state=error). Clients poll GET /servers/{id} or consume instance.create.end notifications.
• Errors: 400 (schema; >40 business exceptions converted at nova/api/openstack/compute/servers.py:835-911), 403 (quota OverQuota, zero-disk flavor, external network), 409 (port in use, ambiguous network, InstanceExists), plus the 404 of a missing flavor converted to 400. See 02-errors § 3.
• Limitations: scheduling failures are never returned synchronously; max_count > 1 with a fixed IP or a port is refused (InvalidFixedIpAndMaxCountRequest, MultiplePortsNotApplicable).

3.2 GET /servers, GET /servers/detail — list servers

• Purpose: list servers of the project (or all projects for admins with all_tenants) with filtering, sorting and paging.
• Actor: project reader (os_compute_api:servers:index / :detail); index:get_all_tenants / detail:get_all_tenants for all_tenants; non-admin filters are restricted.
• Business rules: changes-since/changes-before include recently deleted servers; otherwise deleted=False is forced (nova/api/openstack/compute/servers.py:234-258); listing vm_state=deleted requires admin (403, nova/api/openstack/compute/servers.py:280-285); ip/ip6 filters are delegated to Neutron when the substring-port-filtering extension is present (nova/compute/api.py:3169-3180); page size is capped by [api]/max_limit (default 1000) (nova/conf/api.py:219).
• Flow: build requests and cell0 first, then a scatter-gather over all cells merged in sort order (nova/compute/api.py:3086 get_all, nova/compute/instance_list.py); unreachable cells are skipped or returned as minimal records depending on 2.69 and [api]/list_records_by_skipping_down_cells (nova/conf/api.py:309).
• Outcome: 200 with servers and servers_links (next marker).

3.3 GET /servers/{id}, PUT /servers/{id}, DELETE /servers/{id}

• Show (nova/api/openstack/compute/servers.py:498): reads the instance through the mapping (§ 1.6); 404 if unknown. Fields depend on the microversion (_rewrite/schema-selection_stable-2026.2.json: 15 response schemas from 2.0 to 2.100).
• Update (nova/api/openstack/compute/servers.py:978): changes name, description (2.19+), hostname (2.90+) and, from 2.104, pinned_availability_zone (null unpins the server; re-pinning to another AZ than the current one is a 409) (nova/api/openstack/compute/rest_api_version_history.rst:1341); compute.API.update_instance saves the instance (nova/compute/api.py:3340). No state precondition.
• Delete (nova/api/openstack/compute/servers.py:928): policy servers:delete. If [DEFAULT]/reclaim_instance_interval > 0 the server is soft-deleted (restorable with restore until the periodic reclaim, see 05) and falls back to a hard delete if it never ran (nova/api/openstack/compute/servers.py:948-957). compute.API._delete (nova/compute/api.py:2464):
  1. if a build_requests row still exists, it is deleted and the build is cancelled (nova/compute/api.py:2444, nova/compute/api.py:2484);
  2. otherwise vm_state is kept, task_state=deleting, an instance action delete is recorded, and if the compute service is up an RPC cast terminate_instance (nova/compute/api.py:2780) is sent;
  3. if the host is down or the instance is shelved-offloaded, a local delete happens in nova-api: volumes detached in Cinder, Placement allocations deleted, instance row destroyed (nova/compute/api.py:2731 _local_delete).
  4. 204 on success; 409 if locked, if Placement allocation deletion fails (AllocationDeleteFailed) or the state forbids it.

3.4 Server actions — POST /servers/{id}/action

All actions answer 202 (except os-getConsoleOutput, the console getters and createImage ≥ 2.45 which answer 200) and are asynchronous: the API sets a task_state, records an instance action (instance_actions / instance_actions_events, readable through /servers/{id}/os-instance-actions), and casts to nova-compute or nova-conductor. The full matrix of preconditions is in § 4. Functional groups:

3.5 Volume attachments — /servers/{server_id}/os-volume_attachments

• Attach (POST, nova/api/openstack/compute/volume_attachments.py:205): allowed in active, paused, stopped, resized, soft_deleted, shelved, shelved_offloaded with no task in progress (nova/compute/api.py:5210-5215). For a server that is not offloaded: RPC call attach_volume to the conductor (nova/compute/api.py:5263), which reserves the device name on the host (RPC call reserve_block_device_name, creating the BDM), creates the Cinder attachment (3.44) and casts attach_volume to the host (nova/conductor/manager.py:2267); the response is 200 with the BDM; for a shelved-offloaded server the BDM is created in the database only and the attachment completed immediately (nova/compute/api.py:5162). Tag (2.49+) and delete_on_termination (2.79+) are stored on the BDM.
• Swap / update (PUT, nova/api/openstack/compute/volume_attachments.py:364): admin/service only; before 2.85 only swaps the volume (swap_volume, nova/compute/api.py:5371, used by Cinder volume migration); from 2.85 can also update delete_on_termination.
• Detach (DELETE, nova/api/openstack/compute/volume_attachments.py:395): Cinder begin_detaching, then cast detach_volume to the host (nova/compute/api.py:5299); the root volume cannot be detached (409).

3.6 Interfaces — /servers/{server_id}/os-interface

• Attach (POST, nova/api/openstack/compute/attach_interfaces.py:149): net_id, port_id or fixed_ips; allowed in active, paused, stopped with no task (nova/compute/api.py:5477-5486); RPC call attach_interface to the host (nova/compute/api.py:5511), which creates/binds the port in Neutron and hot-plugs it. Ports with QoS resource requests need a compute able to update Placement allocations (nova/compute/api.py:5445).
• Detach (DELETE, nova/api/openstack/compute/attach_interfaces.py:219): cast detach_interface (nova/compute/api.py:5536).
• List/show read Neutron ports filtered by device_id (nova/api/openstack/compute/attach_interfaces.py:72).

3.7 Server external events — POST /os-server-external-events

• Purpose: let Neutron, Cinder and Cyborg tell Nova that something happened to a server (network-vif-plugged, network-changed, network-vif-unplugged, network-vif-deleted, volume-extended 2.51+, power-update 2.76+, accelerator-request-bound 2.82+, volume-reimaged 2.93+) (nova/api/openstack/compute/schemas/server_external_events.py:29-71).
• Actor: service user (os_compute_api:os-server-external-events:create, role service by default).
• Flow (nova/api/openstack/compute/server_external_events.py:80): instances are looked up across cells; per event: unknown server → event code: 404; missing required tag → 400; server without host → 422; otherwise accepted (200). Accepted events are grouped per host (both source and destination during a migration) and cast to each compute (external_instance_event, nova/compute/api.py:5949-6022). power-update events also record an instance action.
• Outcome: 200 if all accepted, 207 if at least one failed, with per-event status/code. The compute side wakes the waiting wait_for_instance_event (boot, migration) or refreshes the network info cache.

3.8 Server groups — /os-server-groups

• Create (nova/api/openstack/compute/server_groups.py:216): policy affinity, anti-affinity, soft-affinity, soft-anti-affinity; from 2.64 a single policy plus rules.max_server_per_host for anti-affinity, only when all computes are at service version ≥ 33 (nova/api/openstack/compute/server_groups.py:78). Quota server_groups checked before and re-checked after creation when [quota]/recheck_quota (nova/api/openstack/compute/server_groups.py:263-277). Stored in the API DB (instance_groups, instance_group_policy, instance_group_member).
• Use: the group is passed in os:scheduler_hints.group at boot; the scheduler filters enforce it, and the compute host re-checks hard (anti-)affinity at build time (late check, see 05).
• Delete removes the group but not its servers.

3.9 Key pairs — /os-keypairs

• Create/import (nova/api/openstack/compute/keypairs.py:55): from 2.92 public_key is mandatory (server-side generation removed); type ssh or x509 (2.2+); admins may act for another user_id (2.10+). Quota key_pairs is checked per user (nova/compute/api.py:6981). Key pairs live in the API DB (key_pairs), scoped to the user, not the project. 409 if the name exists (nova/api/openstack/compute/keypairs.py:107).
• At boot, the key pair is copied into the instance (instance_extra.keypairs); later deletion of the key pair does not affect existing servers.

3.10 Services, hypervisors, aggregates, availability zones (admin)

• Services (/os-services): list nova-compute, nova-conductor, nova-scheduler records from every cell, with state computed by the servicegroup driver (heartbeat age vs [DEFAULT]/service_down_time). PUT (2.53+, by service UUID) enables/disables a compute (disabled_reason) or sets forced_down (fencing, used with evacuate) (nova/api/openstack/compute/services.py:399). Disabling also toggles the COMPUTE_STATUS_DISABLED trait in Placement through the compute host [inferred]. DELETE (nova/api/openstack/compute/services.py:245) refuses a compute that still hosts instances (409), removes it from its aggregates, deletes its Placement resource providers, then deletes the service and compute node rows.
• Hypervisors (/os-hypervisors): read compute_nodes of all cells; UUIDs as ids from 2.53; statistics and uptime removed after 2.87 (404). servers/search sub-routes replaced by query parameters from 2.53.
• Aggregates (/os-aggregates, nova/api/openstack/compute/aggregates.py:57): host aggregates in the API DB. add_host/remove_host mirror the membership into Placement aggregates of the host's resource provider (nova/compute/api.py:6833, nova/compute/api.py:6939) and refuse changes that would move existing instances to another AZ (nova/compute/api.py:6752). Setting availability_zone metadata defines AZs. POST /os-aggregates/{id}/images (2.81+) casts cache_images to every host of the aggregate through conductor (image pre-caching).
• Availability zones (/os-availability-zone, /detail): derived from aggregate metadata and services; [DEFAULT]/default_availability_zone for hosts in no AZ.

3.11 Quotas and limits

• /os-quota-sets/{project_id} show/detail/update/delete/defaults and /os-quota-class-sets/{id} (nova/api/openstack/compute/quota_sets.py:123). With the default [quota]/driver = nova.quota.DbQuotaDriver limits live in the API DB (quotas, project_user_quotas, quota_classes) and usage is counted from cell databases and Placement at check time (no reservations). With nova.quota.UnifiedLimitsDriver, limits come from Keystone unified limits and PUT/DELETE are refused (400) (nova/api/openstack/compute/quota_sets.py:181).
• Resources hidden by microversion: floating_ips, fixed_ips, security_groups, security_group_rules, networks disappear at 2.36; injected_file* at 2.57 (nova/api/openstack/compute/quota_sets.py:109).
• GET /limits (nova/api/openstack/compute/limits.py:50) returns absolute limits and usage of the project.

3.12 Migrations and instance actions

• GET /os-migrations (admin, nova/api/openstack/compute/migrations.py:191): migrations of all cells with filters, paging (2.59+), user_id/project_id (2.80+).
• /servers/{id}/migrations (2.23+): in-progress live migrations; POST …/{mid}/action {"force_complete": null} (2.22+) casts live_migration_force_complete (nova/compute/api.py:5642); DELETE …/{mid} (2.24+) aborts a running or (2.65+) queued live migration (nova/compute/api.py:5672).
• /servers/{id}/os-instance-actions[/{request_id}]: history of actions and their events (compute-side steps with tracebacks for admins); works for deleted servers from 2.21.

3.13 Other server sub-resources

4. Server action matrix

Generated from the nova/compute/api.py decorators of the method each action calls. In state(...), an omitted task_state means **task_state must be None** (no operation in progress) and the server must have been launched once (nova/compute/api.py:142). check_instance_lock → 409 for non-admins on a locked server; check_instance_host() → 409 if the server has no host, check_is_up=True → 503 if its compute service is down; reject_*/block_* decorators refuse features the operation does not support (vTPM, vDPA, memory encryption, accelerators, extended resource requests, shares) with 400/409. Several actions call other compute.API methods internally; the precise path is noted below the table.

Notes on rows the generator cannot resolve by itself:

• reboot → _soft_reboot requires vm_state in ALLOW_SOFT_REBOOT (active) and no task; _hard_reboot accepts active, stopped, paused, suspended, error and an in-progress reboot or resume (ALLOW_REBOOT), so a hard reboot can interrupt a stuck soft reboot (nova/compute/api.py:3644-3671, nova/compute/vm_states.py:70-73). Task states rebooting / rebooting_hard, instance action reboot, cast reboot_instance.
• os-stop → force_stop sets powering-off, records stop, casts stop_instance (nova/compute/api.py:2858-2867).
• createImage (nova/api/openstack/compute/servers.py:1456-1463) → for an image-backed server compute.API.snapshot (nova/compute/api.py:3447) sets image_snapshot_pending and casts snapshot_instance; for a volume-backed server snapshot_volume_backed quiesces the guest (RPC call), creates Cinder snapshots and registers an image in Glance inside the API request (nova/compute/api.py:3504-3631). From 2.45 the response body carries image_id and the code stays 202.
• os-resetState writes vm_state (active or error) and clears task_state directly (nova/api/openstack/compute/admin_actions.py:71-92); no RPC.
• addSecurityGroup / removeSecurityGroup update the security groups of every port of the server in Neutron (nova/network/security_group_api.py) [inferred: one call per port].
• addFloatingIp / removeFloatingIp (≤ 2.43) associate a Neutron floating IP with the server's port (nova/api/openstack/compute/floating_ips.py:200).

5. Lifecycle of a server

vm_state is the stable state, task_state the operation in progress; the API status is derived from both (§ 1.5). Simplified (main transitions):

stateDiagram-v2
  [*] --> BUILD: POST /servers (API, build_requests row)
  BUILD --> ACTIVE: build_and_run_instance succeeded (RPC cast conductor→compute)
  BUILD --> ERROR: no valid host (conductor, instance in cell0) / spawn failure (compute)
  ACTIVE --> SHUTOFF: os-stop (API→cast stop_instance) / guest shut down (compute _sync_power_states)
  SHUTOFF --> ACTIVE: os-start (cast start_instance)
  ACTIVE --> PAUSED: pause
  PAUSED --> ACTIVE: unpause
  ACTIVE --> SUSPENDED: suspend
  SUSPENDED --> ACTIVE: resume
  ACTIVE --> RESCUE: rescue
  RESCUE --> ACTIVE: unrescue
  ACTIVE --> VERIFY_RESIZE: resize / migrate (conductor + scheduler, finish_resize on target)
  SHUTOFF --> VERIFY_RESIZE: resize / migrate
  VERIFY_RESIZE --> ACTIVE: confirmResize / revertResize / auto-confirm (periodic _poll_unconfirmed_resizes)
  ACTIVE --> SHELVED: shelve (snapshot to Glance)
  SHELVED --> SHELVED_OFFLOADED: shelveOffload / periodic _poll_shelved_instances
  SHELVED_OFFLOADED --> ACTIVE: unshelve (conductor + scheduler)
  ACTIVE --> SOFT_DELETED: DELETE with reclaim_instance_interval > 0
  SOFT_DELETED --> ACTIVE: restore
  SOFT_DELETED --> DELETED: forceDelete / periodic _reclaim_queued_deletes
  ACTIVE --> DELETED: DELETE (cast terminate_instance, or local delete if host down)
  ERROR --> ACTIVE: os-resetState / rebuild / hard reboot
  DELETED --> [*]

Live migration, evacuation, rebuild, reboot, snapshot and backup keep the vm_state and only move task_state (migrating, rebuilding, rebooting, image_snapshot…); a failure during them either restores the previous state or sets ERROR with an instance fault, depending on the step (see 02-errors § 4).

6. Other resources with states

• Migration (migrations.status): pre-migrating → migrating → post-migrating → finished → confirmed / reverted, or error/failed; live migrations: accepted/queued → preparing → running → completed, or cancelled/failed/error. Read through /os-migrations and /servers/{id}/migrations.
• Service: enabled/disabled (+ disabled_reason) set by the API; up/down computed from the heartbeat (nova/servicegroup/drivers/db.py); forced_down set by the API (2.11+).
• Instance action events: start/finish with result Success/Error, written by the compute and conductor wrap_instance_event decorator (see 05).

7. Deprecated and removed families

8. Spec/code gaps

• The api-ref documents 251 operations (_rewrite/api-ref_stable-2026.2.json) while the code exposes 265 (actions counted one by one). Differences come from: removed (410) APIs that are not all documented, the /os-volumes_boot alias (code only), and action keys documented under POST /servers/{server_id}/action with one rest_method per action. The detailed comparison is in _rewrite/rewrite-pack-index_stable-2026.2.md (part 5).
• GET /os-hypervisors/detail declares no policy operations entry matching its path: the rule os_compute_api:os-hypervisors:list-detail documents /os-hypervisors/details (nova/policies/hypervisors.py:56); the rule is still enforced in the handler (nova/api/openstack/compute/hypervisors.py:290), only the documented path is wrong.
• GET /flavors has no policy check at all (public), consistent with the api-ref.

9. Metadata API (nova-metadata-api)

A second WSGI application (etc/nova/api-paste.ini:4, nova/api/metadata/handler.py:47) serves /openstack/* and EC2-style /latest/meta-data/* to guests:

• Behind the Neutron metadata proxy ([neutron]/service_metadata_proxy = True): the instance is identified by X-Instance-ID, X-Tenant-ID and X-Instance-ID-Signature (HMAC-SHA256 of the instance id with [neutron]/metadata_proxy_shared_secret); missing headers → 400, bad signature → 403 (nova/api/metadata/handler.py:159, nova/api/metadata/handler.py:298-315).
• Direct (no proxy): the instance is found by its fixed IP (X-Forwarded-For when [api]/use_forwarded_for) (nova/api/metadata/handler.py:141).
• Responses are cached in oslo.cache (metadata-<address> / metadata-<instance_id> keys) for [api]/metadata_cache_expiration seconds (nova/api/metadata/handler.py:51-93).
• Content: instance metadata, user data, key pair, network data (from the info cache), vendor data (static JSON and/or a dynamic REST call to configured vendordata services, nova/api/metadata/vendordata_dynamic.py), password (POST by the guest).

Source: reverse-spec-nova/01-rest-api_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.