Images service API reference

These endpoints operate on images: listing, creating, updating, deleting, uploading and downloading image data, and sharing images with other projects. They are the OpenStack Glance v2 API. For the upstream specification, see the Image (Glance) API reference.

In the paths below, {image_id} is the UUID of an image and {member_id} is the UUID of a member project. Replace both with real IDs.

Service base URL#

Replace {region} with your region. Currently only us-east-1 is available. Discover the image endpoint from the service catalog:

openstack catalog show image

The examples below write the image base URL as {glance_base}.

Authentication#

Every request requires a valid Keystone token in the X-Auth-Token header. Issue one with openstack token issue. A missing or expired token returns 401 Unauthorized.

Image status#

An image moves through these states. Several endpoints have preconditions tied to the current status, so check it before acting:

List images#

GET {glance_base}/v2/images

Returns 200 OK. The body is an object with an images array plus the first, next, and schema keys used for pagination:

{
  "images": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Rocky-10",
      "status": "active",
      "visibility": "public",
      "size": 536870912,
      "disk_format": "qcow2",
      "container_format": "bare"
    }
  ],
  "first": "/v2/images",
  "schema": "/v2/schemas/images"
}

Filter and page with query parameters, for example ?visibility=public&limit=2. The next key, when present, carries the path and marker for the following page.

Show image details#

GET {glance_base}/v2/images/{image_id}

Returns 200 OK with a flat image object (the attributes are top-level, not wrapped in an image key). A typical Quake AI public image carries about 38 attributes. Beyond the core fields, Glance injects provider and hardware properties that the endpoint list above does not show:

direct_url, stores, locations          # storage backend details
os_hash_algo, os_hash_value            # content digest (SHA-512 by default)
owner_specified.openstack.md5          # owner-supplied checksums
owner_specified.openstack.sha256
hw_disk_bus, hw_scsi_model             # hardware bus hints for the guest
hw_qemu_guest_agent                    # guest-agent expectation
hw_vif_multiqueue_enabled              # multiqueue virtio-net hint

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Rocky-10",
  "status": "active",
  "visibility": "public",
  "size": 536870912,
  "virtual_size": 10737418240,
  "disk_format": "qcow2",
  "container_format": "bare",
  "min_disk": 10,
  "min_ram": 1024,
  "protected": false,
  "os_hash_algo": "sha512",
  "tags": [],
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-01T12:05:00Z",
  "schema": "/v2/schemas/image"
}

A request for an unknown ID returns 404 Not Found.

Create an image#

POST {glance_base}/v2/images

Send Content-Type: application/json with the image metadata. Returns 201 Created with the new image as a flat object.

{
  "name": "my-image",
  "disk_format": "qcow2",
  "container_format": "bare",
  "visibility": "private"
}

Upload image data#

PUT {glance_base}/v2/images/{image_id}/file

Send the binary image as the request body with Content-Type: application/octet-stream:

Content-Type: application/octet-stream

Returns 204 No Content with an empty body. The target image must be in status queued. After a successful upload the status moves queued, then saving, then active, and Glance populates size, checksum (MD5), and virtual_size automatically.

Download image data#

GET {glance_base}/v2/images/{image_id}/file

Returns 200 OK with the image bytes in the registered disk_format (raw, qcow2, vmdk, and so on). The endpoint supports HTTP Range requests, so you can resume an interrupted transfer with curl -C -. Write large downloads to a file with curl -o OUTPUT_FILE and verify them against the checksum (MD5) and os_hash_value (SHA-512) fields from GET {glance_base}/v2/images/{image_id}.

Update an image#

PATCH {glance_base}/v2/images/{image_id}

[
  { "op": "replace", "path": "/name", "value": "new-name" },
  { "op": "add", "path": "/protected", "value": true }
]

Returns 200 OK with the updated image object.

Delete an image#

DELETE {glance_base}/v2/images/{image_id}

Returns 204 No Content. Deleting an image that does not exist returns 404 Not Found. An image still referenced by a running server can return 409 Conflict.

Image members#

Image members control sharing. A member is a project that an image owner grants access to. Member operations apply to one image at a time.

List image members#

GET {glance_base}/v2/images/{image_id}/members

Returns 200 OK with a members array for a shared image. Any other visibility returns 403 Forbidden.

Add an image member#

POST {glance_base}/v2/images/{image_id}/members

Send Content-Type: application/json with the consumer project ID. Returns 200 OK with the new member in status pending.

{
  "member": "f0e9d8c7-b6a5-4321-9f8e-7d6c5b4a3210"
}

Show image member details#

GET {glance_base}/v2/images/{image_id}/members/{member_id}

Returns 200 OK with the member's status (pending, accepted, or rejected).

Update image member#

PUT {glance_base}/v2/images/{image_id}/members/{member_id}

The member project calls this endpoint to accept or reject a share. Send Content-Type: application/json:

{
  "status": "accepted"
}

Returns 200 OK with the updated member object.

Remove an image member#

DELETE {glance_base}/v2/images/{image_id}/members/{member_id}

Returns 204 No Content.

Schemas#

Glance publishes machine-readable JSON Schema documents for its resources. Use them to discover the full attribute set, including provider-injected properties:

GET {glance_base}/v2/schemas/image
GET {glance_base}/v2/schemas/member

Both return 200 OK.

Error responses#

The Image (Glance) service returns errors as HTML, not JSON. This differs from the Compute (Nova) API, which returns a structured JSON error envelope. Branch on the HTTP status code rather than parsing the response body, since a client that expects JSON sees a parse error before it reads the status. For the Compute API error envelope and cross-service guidance, see the Compute API error reference.