cinder — REST API

REST API — cinder — branch stable/2026.2

Branch stable/2026.2 @ c117f9cf08b4 (29.0.0-1-gc117f9cf0) — repository https://opendev.org/openstack/cinder — analysed on 2026-10-28

This file describes the Block Storage API v3 as the code serves it. The operation table (§ 3) was extracted from the live router (cinder.api.v3.router.APIRouter with the contrib extensions loaded) rather than from the api-ref, so it lists what a client can really call. The machine-readable version is [_rewrite/routes_stable-2026.2.json](_rewrite/routes_stable-2026.2.json) and [_rewrite/openapi_stable-2026.2.json](_rewrite/openapi_stable-2026.2.json). Errors are detailed in 02-errors_stable-2026.2.md, and the asynchronous follow-up of each operation in 05-async-processing_stable-2026.2.md.

1. Conventions shared by every endpoint

1.1 Entry point and pipeline

• Root: osapi_volume composite (etc/cinder/api-paste.ini:5-8): / → version list, /healthcheck → oslo.middleware health check (disabled by the file /etc/cinder/healthcheck_disable, etc/cinder/api-paste.ini:55), /v3 → the API. /v1 and /v2 are removed and only produce a log warning (cinder/api/__init__.py:30-44).
• v3 pipeline with auth_strategy = keystone (etc/cinder/api-paste.ini:15): request_id → cors → http_proxy_to_wsgi → faultwrap → sizelimit → osprofiler → authtoken (keystonemiddleware) → keystonecontext → apiv3. The pipeline is chosen by pipeline_factory from [DEFAULT]/auth_strategy (cinder/api/middleware/auth.py:47-58); noauth replaces the last two filters by a fake authentication that trusts X-Auth-Token: user:project and sets is_admin=True (cinder/api/middleware/auth.py:132-176).
• Request context: CinderKeystoneContext builds cinder.context from the headers set by keystonemiddleware and answers 401 without body when no user is identified (cinder/api/middleware/auth.py:105-126). X-Forwarded-For is trusted only with [DEFAULT]/use_forwarded_for (cinder/api/middleware/auth.py:33-37).

1.2 URLs

• Every resource exists twice: /v3/{project_id}/<resource> and /v3/<resource> (cinder/api/v3/router.py:60-95, cinder/api/openstack/wsgi.py:1289-1307). The project-less form is accepted at every microversion: microversion 3.67 only announces it, nothing checks it.
• {project_id} must match [DEFAULT]/project_id_regex (default [0-9a-f\-]+, cinder/api/openstack/__init__.py:25-29). When present, it must equal the project of the token, otherwise 400 "Malformed request url" (cinder/api/openstack/wsgi.py:897-901).
• A trailing .json is accepted and forces JSON (cinder/api/openstack/wsgi.py:232-254, cinder/api/openstack/wsgi.py:1281-1287).

1.3 Microversions

• Header OpenStack-API-Version: volume 3.x (cinder/api/openstack/wsgi.py:62-64). Without it the request is served at 3.0, the minimum, not the maximum (cinder/api/openstack/wsgi.py:326-327). latest means 3.71.
• Range 3.0 – 3.71 (cinder/api/openstack/api_version_request.py:165-166); history in [_rewrite/microversions_stable-2026.2.md](_rewrite/microversions_stable-2026.2.md).
• Out of range → 406; malformed → 400; header present without a volume entry → VersionNotFoundForAPIMethod (cinder/api/openstack/wsgi.py:292-327, cinder/api/openstack/wsgi.py:820-829).
• A versioned method called outside its range → 404 without explanation, as if the route did not exist (cinder/api/openstack/wsgi.py:1001-1010).
• Every response carries OpenStack-API-Version: volume <served version> and Vary: OpenStack-API-Version (cinder/api/openstack/wsgi.py:957-964).

1.4 Body-dispatched actions

POST …/{id}/action dispatches on the single key of the JSON body ({"os-extend": {...}}): action_peek_json rejects a body with more than one key ("too many body keys", 400) and an unknown key gives 400 "There is no such action: …" (cinder/api/openstack/wsgi.py:565-580, cinder/api/openstack/wsgi.py:858-866, cinder/api/openstack/wsgi.py:968-999). The same fallback also maps POST /types, PUT /types/{id}, DELETE /types/{id} and DELETE /groups/{id} to @wsgi.action methods named create, update, delete (cinder/api/openstack/wsgi.py:977-985).

1.5 Request validation

• JSON-schema validation through @validation.schema(schema, min, max), which applies a schema only inside its microversion range (cinder/api/validation/__init__.py:27-63). The 112 schemas are in [_rewrite/request-schemas_stable-2026.2.json](_rewrite/request-schemas_stable-2026.2.json); which one applies per operation and microversion is in routes_stable-2026.2.json (variants[].schemas).
• Accepted content types: application/json and application/vnd.openstack.volume+json; anything else → 415 (cinder/api/openstack/wsgi.py:46-55, cinder/api/openstack/wsgi.py:836-843).
• Body size limited by oslo.middleware sizelimit ([oslo_middleware]/max_request_body_size).

1.6 Responses

• Error body: {"<faultName>": {"code": <status>, "message": "<text>"}} with faultName among badRequest, unauthorized, forbidden, itemNotFound, badMethod, conflictingRequest, overLimit, badMediaType, notImplemented, serviceUnavailable, otherwise computeFault (cinder/api/openstack/wsgi.py:1310-1363).
• Request ID: x-openstack-request-id (oslo RequestId, cinder/api/middleware/request_id.py:25-71) and the legacy x-compute-request-id (cinder/api/openstack/wsgi.py:1369-1372).
• Lists: limit (bounded by [DEFAULT]/osapi_max_limit, default 1000), marker, offset, sort/sort_key/sort_dir, with_count (3.45); filters allowed per resource by resource_filters.json (cinder/api/common.py:38-45, cinder/api/common.py:63-141). Next-page links are volumes_links, snapshots_links…

1.7 Authorisation

Policies (167 default rules in [_rewrite/policies_stable-2026.2.json](_rewrite/policies_stable-2026.2.json)) are checked in the business layer (context.authorize(...) in cinder/volume/api.py, cinder/backup/api.py…), not in the router. Defaults on this branch:

• rule:xena_system_admin_or_project_member = (role:admin) or (role:member and project_id:%(project_id)s) for writes (56 rules);
• rule:xena_system_admin_or_project_reader for reads (27 rules);
• rule:admin_api = is_admin:True or (role:admin and is_admin_project:True) for operator actions (78 rules).

So role:admin in any project is a cloud administrator by default (cinder/policies/base.py:69-184). A denial gives 403 Policy doesn't allow <rule> to be performed..

2. Functional description by area

2.1 Volumes (/volumes)

POST /volumes — create a volume

• Purpose: allocate a block device of size GiB, empty or populated from a snapshot, another volume, an image or a backup.
• Actor: project member (volume:create, or volume:create_from_image when imageRef is set, cinder/volume/api.py:240-243).
• Preconditions: the source (snapshot, volume, backup) is visible to the caller; a volume type is resolved: the requested one, otherwise the project default type (default_volume_types table, API 3.62), otherwise [DEFAULT]/default_volume_type. A misconfigured default gives 500 VolumeTypeDefaultMisconfiguredError (cinder/volume/volume_types.py:214-240, cinder/api/v3/volumes.py:468-473).
• Business rules:
  • size must be a positive integer, or is taken from the source when omitted (cinder/api/v3/volumes.py:444-450, cinder/volume/api.py:261-267); it must be ≥ the source size (cinder/volume/flows/api/create_volume.py:174-205), and within the volume type's provisioning:min_vol_size / max_vol_size (cinder/volume/api.py:269-270).
  • The multiattach parameter is refused: multi-attach comes from the volume type (cinder/api/v3/volumes.py:454-461).
  • A different type from the source's is allowed only if a retype between both types would be possible (cinder/volume/api.py:295-314).
  • Availability zone: requested, otherwise the source's, otherwise default_availability_zone / storage_availability_zone; it must be one of the zones of live cinder-volume services (and of the type's RESKEY:availability_zones), unless allow_availability_zone_fallback (cinder/volume/flows/api/create_volume.py:260-350).
  • Metadata keys and values are limited to 255 characters (cinder/volume/api.py:325).
  • Quotas volumes, gigabytes, volumes_<type>, gigabytes_<type> are reserved, and per_volume_gigabytes is checked (cinder/volume/flows/api/create_volume.py:676-731).
• Flow:
  1. (synchronous) Validation, quota reservation, INSERT volumes with status creating, quota commit, then RPC cast create_volume to cinder-scheduler (cinder/volume/flows/api/create_volume.py:889-922).
  2. (asynchronous) The scheduler filters and weighs the backends and casts create_volume to the chosen cinder-volume (05 § 2.1).
  3. (asynchronous) The volume manager runs its create flow (raw, from snapshot, clone, image with image-volume cache, backup), and sets available or error (05 § 3.1).
• Outcome: 202 with the volume in creating; the client polls GET /volumes/{id} until available or error. On error, the reason is in GET /messages (API ≥ 3.3).
• Effects visible elsewhere: notifications volume.create.start/end; Glance download when created from an image; Barbican key creation for an encrypted type.
• Limitations: when the scheduler finds no backend, the volume goes to error with user message VOLUME_001_003 (no HTTP error).

GET /volumes, /volumes/detail, /volumes/{id}, /volumes/summary

• Purpose: list or show volumes; summary (3.12) returns the total count and size, and metadata keys (3.36).
• Rules: non-admins only see their project; all_tenants, host and migration attributes are admin-only (policies volume_extension:volume_host_attribute, …mig_status_attribute, …tenant_attribute). Filters are checked against resource_filters.json; time comparisons on created_at/updated_at use gt/gte/eq/neq/lt/lte (3.60) (cinder/api/v3/volumes.py:114-213).
• Response by microversion: group_id (3.13), provider_id (3.21), service_uuid and shared_targets (3.48), cluster_name (3.61), volume_type_id (3.63), encryption_key_id (3.64), consumes_quota (3.65); shared_targets may be null from 3.69 (cinder/api/v3/views/volumes.py:201).

PUT /volumes/{id}

Updates name, description, metadata (cinder/volume/api.py:571-593); notification volume.update.start/end.

DELETE /volumes/{id}[?cascade=true&force=true]

• Preconditions (one conditional UPDATE): not attached, not migrating, not in a group, no snapshot (unless cascade), status in available, error, error_restoring, error_extending, error_managing (unless force, 3.23 and policy volume:force_delete) (cinder/volume/api.py:414-566, cinder/api/v3/volumes.py:68-95).
• Flow: status → deleting; cascaded snapshots → deleting; image-volume cache entry evicted; the encryption key is deleted from the key manager before the RPC, which makes the deletion irreversible; cast delete_volume to the volume's backend (cinder/volume/api.py:532-566). A volume never scheduled (no host) is deleted directly in the API, quota released (cinder/volume/api.py:423-455).
• Outcome: 202; the volume disappears from lists when the manager finishes, or ends in error_deleting.

POST /volumes/{id}/action — the volume actions

2.2 Attachments (/attachments, 3.27+) — what Nova uses

• POST /attachments: reserve the volume for an instance (volume:attachment_create). The volume must not be in an error status; status → reserved with an attachment row reserved (cinder/volume/api.py:2476-2523). With a connector, the volume service is called synchronously (attachment_update) to export the volume and returns connection_info. A driver exception becomes 500 "Unable to create attachment for volume" (cinder/api/v3/attachments.py:200-211). mode (rw/ro) from 3.54.
• PUT /attachments/{id}: give the connector of the compute host (attachment_update, serialised by a lock attachment_update-<volume_id>-<host>); 409 when the volume is in error or when a non-multiattach volume already has a connection on another host (cinder/volume/api.py:2525-2586).
• **POST /attachments/{id}/action os-complete** (3.44): attachment → attached, volume → in-use, notification volume.attach.end (cinder/api/v3/attachments.py:289-306).
• DELETE /attachments/{id}: allowed for a connected attachment only if the request carries a service token (Nova) or if Nova no longer knows the attachment; otherwise **409 ConflictNovaUsingAttachment** (bug 2004555, cinder/volume/api.py:2588-2661). Calls attachment_delete on the volume service, which unexports and returns the remaining attachments.

2.3 Snapshots (/snapshots, /snapshots/{id}/metadata)

• POST /snapshots: volume available, or in-use with force; quotas snapshots, gigabytes; status creating; cast create_snapshot to the volume's backend (cinder/volume/api.py:980-1223). Snapshots of a volume in-use are refused when force is false.
• DELETE /snapshots/{id}: status available or error, not part of a group snapshot; cast delete_snapshot (cinder/volume/api.py:1225-1257).
• Actions: os-reset_status, os-force_delete (admin), os-update_snapshot_status (used by Nova for assisted snapshots), os-unmanage.

2.4 Backups (/backups)

• POST /backups: volume available (or in-use with force) or a snapshot available; incremental requires a previous available backup; quotas backups, backup_gigabytes; volume → backing-up; backup creating; cast create_backup to the scheduler, which picks a cinder-backup host in the same AZ (cinder/backup/api.py:218-374). Metadata (3.43), availability zone (3.51).
• POST /backups/{id}/restore: into a new or existing volume (restoring-backup); GET /backups/{id}/export_record, POST /backups/import_record (admin): move backup records between deployments (cinder/backup/api.py:376-648).
• DELETE /backups/{id}: available or error, no dependent incremental backup.

2.5 Volume types, extra specs, encryption, access, QoS, default types

• /types (admin writes through types_manage, cinder/api/contrib/types_manage.py:54-160); /types/{id}/extra_specs; /types/{id}/encryption (provider, cipher, key size, control location); /types/{id}/os-volume-type-access and the addProjectAccess/removeProjectAccess actions for private types; /qos-specs with associate/disassociate as GET requests with a query string (cinder/api/contrib/qos_specs_manage.py:229-370).
• /default-types (3.62): per-project default type; the project is checked in Keystone (cinder/api/api_utils.py:238-262, cinder/api/v3/default_types.py:42-116).
• Group types and group specs (3.11).

2.6 Groups and group snapshots (3.13 / 3.14), consistency groups (deprecated)

Generic volume groups bound to a backend; actions delete (with delete-volumes), create-from-src, reset_status, enable_replication, disable_replication, failover_replication, list_replication_targets (3.38). Consistency groups (/consistencygroups, /cgsnapshots) are kept for compatibility and map to the same group code (cinder/group/api.py:109-1151).

2.7 Transfers (/volume-transfers 3.55, /os-volume-transfer)

• Create: volume available → awaiting-transfer; returns once an auth_key (16 hex characters by default) stored as HMAC-SHA1(salt, auth_key) with an 8-character salt (cinder/transfer/api.py:106-176). no_snapshots (3.55); encrypted volumes allowed from 3.70 (cinder/api/v3/volume_transfer.py:100).
• Accept POST …/{id}/accept: compares the HMAC (else **400 InvalidAuthKey), reserves quota in the recipient project and releases it in the donor project, then **calls accept_transfer on the volume service (cinder/transfer/api.py:235-330).

2.8 Quotas and limits

/os-quota-sets/{project_id} (show with ?usage=true, update, delete = reset to defaults, defaults), /os-quota-class-sets/{class}; /limits returns absolute limits and usage (cinder/api/contrib/quotas.py:69-160, cinder/api/v3/limits.py:27). Resources: volumes, snapshots, gigabytes, backups, backup_gigabytes, groups, per_volume_gigabytes, plus per-type volumes_<type>, snapshots_<type>, gigabytes_<type>.

2.9 Operator APIs

/os-services (list, enable, disable, freeze/thaw, failover_host, get-log/set-log 3.32), /clusters (3.7), /workers/cleanup (3.24, re-run cleanup of resources left by a dead service), /scheduler-stats/get_pools, /capabilities/{host}, /os-hosts (deprecated), /manageable_volumes and /manageable_snapshots (list unmanaged backend objects), /os-volume-manage and /os-snapshot-manage (adopt them), /messages (3.3, user-facing asynchronous errors), /resource_filters (3.33), /os-availability-zone, /extensions.

3. Operation table

218 operations (the 52 body actions counted separately), extracted from the router. "Microversion" gives the range of each implementation (3.27+, or 3.0–3.15 / 3.16+ when the handler changes). An empty cell means available from 3.0. "Policy rule(s)" comes from the operations declared by the policy rules; the code may check more rules than these.

Plus GET / (version list, 300, cinder/api/versions.py:87-92) and GET /v3/ (version document, cinder/api/versions.py:76-79). The router also declares routes whose controller has no method (for example GET /volumes/new, PUT /limits/{id}): they answer 404, or 400 "There is no such action" when the controller has body actions. They are listed in [_rewrite/routes-unimplemented_stable-2026.2.json](_rewrite/routes-unimplemented_stable-2026.2.json) and must not be implemented by a rewrite.

Spec/code mismatches

• os-extend_volume_completion is documented as added in 3.71, but mv.EXTEND_VOLUME_COMPLETION is never used: the action exists at every microversion for whoever passes the policy (cinder/api/microversions.py:182, cinder/api/contrib/admin_actions.py:205-214).
• The policy operations contain 13 entries that match no route (PUT /clusters/{id}, POST /backups/{id}/export_record instead of GET, GET /os-quota-sets/{id}/default instead of defaults, /volume_transfers instead of /volume-transfers…), listed in [_rewrite/policy-operations-unmatched_stable-2026.2.json](_rewrite/policy-operations-unmatched_stable-2026.2.json). 58 operations have no policy rule in any operations list; their checks are in the code.
• associate, disassociate and disassociate_all on QoS specs change data with GET (cinder/api/contrib/qos_specs_manage.py:262-370).
• os-hosts and consistencygroups/cgsnapshots are deprecated but routed.

4. Lifecycles

Volume

stateDiagram-v2
  [*] --> creating: POST /volumes (API)
  creating --> available: create flow done (cinder-volume)
  creating --> error: no valid backend (scheduler) / driver failure (cinder-volume)
  creating --> downloading: create from image (cinder-volume)
  downloading --> available: image copied
  available --> reserved: POST /attachments or os-reserve (API)
  reserved --> attaching: os-attach (API)
  reserved --> in_use: attachments os-complete (API)
  attaching --> in_use: attach_volume (RPC call)
  in_use --> detaching: os-begin_detaching (API)
  detaching --> available: detach_volume / attachment_delete (RPC call)
  available --> extending: os-extend (API)
  in_use --> extending: os-extend >= 3.42 (API)
  extending --> available: extend_volume (cinder-volume)
  extending --> in_use: extend_volume (attached)
  extending --> error_extending: driver failure
  available --> retyping: os-retype (API)
  retyping --> available: retype done
  available --> uploading: os-volume_upload_image (API)
  uploading --> available: copy_volume_to_image done
  available --> backing_up: POST /backups (API)
  backing_up --> available: backup done (cinder-backup)
  available --> restoring_backup: POST /backups/{id}/restore (API)
  restoring_backup --> available: restore done
  restoring_backup --> error_restoring: restore failure
  available --> awaiting_transfer: POST /volume-transfers (API)
  awaiting_transfer --> available: accept or DELETE transfer
  available --> reverting: revert (API)
  reverting --> available: revert_to_snapshot (cinder-volume)
  available --> deleting: DELETE (API)
  error --> deleting: DELETE (API)
  deleting --> [*]: delete_volume (cinder-volume)
  deleting --> error_deleting: driver failure
  available --> maintenance: migration (cinder-volume)

in_use, backing_up, restoring_backup, awaiting_transfer stand for in-use, backing-up, restoring-backup, awaiting-transfer (Mermaid identifiers cannot contain -). The statuses are listed in cinder/objects/fields.py:162-191; os-reset_status can set any of them.

Attachment (volume_attachment.attach_status)

stateDiagram-v2
  [*] --> reserved: POST /attachments without connector
  reserved --> attaching: PUT /attachments/{id} with connector (connection_info returned)
  [*] --> attaching: POST /attachments with connector
  attaching --> attached: os-complete
  attached --> detached: DELETE /attachments/{id}
  reserved --> detached: DELETE /attachments/{id}
  attaching --> error_attaching: driver failure
  detached --> [*]

Statuses from cinder/objects/fields.py:145-152. [inferred] The intermediate attaching value is written by the volume manager's attachment_update.

Snapshot and backup

stateDiagram-v2
  [*] --> creating: POST /snapshots
  creating --> available: create_snapshot (cinder-volume)
  creating --> error: driver failure
  available --> deleting: DELETE
  error --> deleting: DELETE
  deleting --> [*]
  deleting --> error_deleting: driver failure
  available --> backing_up: backup of the snapshot
  backing_up --> available
  available --> restoring: revert (volume)
  restoring --> available

stateDiagram-v2
  [*] --> creating: POST /backups
  creating --> available: create_backup (cinder-backup)
  creating --> error: driver failure / backup service down
  available --> restoring: POST /backups/{id}/restore
  restoring --> available: restore done
  available --> deleting: DELETE
  error --> deleting: DELETE
  deleting --> deleted: delete_backup (cinder-backup)
  deleting --> error_deleting: driver failure

Statuses from cinder/objects/fields.py:25-36 and cinder/objects/fields.py:113-127.

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