Images#

Use the images API operations to list, delete, and update images.

List images#

GET /images

Lists public virtual machine (VM) images.

This operation returns images you created, shared images that you accepted, and standard images. For more information about standard images, see Standard images. The response conforms to the schema found in Get images schema.

This operation returns a subset of the larger collection of images and a link that you can use to get the next set of images. Always check for the presence of a next link and use it as the URI in a subsequent GET request. Follow this pattern until a next link is no longer provided. The next link preserves any query parameters that you send in your initial request. You can use the first link to jump back to the first page of the collection. If you prefer to paginate through images manually, use the limit and marker parameters.

The List Images operation accepts several types of query parameters that you can use to filter the results of the returned collection.

A client can provide direct comparison filters by using most image attributes, such as name=Ubuntu, visibility=public, and so on. A client cannot filter on tags or anything defined as a link in the json-schema, such as self, file, or schema.

You can use the size_min and size_max query parameters to perform greater-than and less-than filtering of images based on their size attribute. The size is measured in bytes and refers to the size of an image when it is stored on disk.

For example, sending a size_min filter of 1048576 and size_max of 4194304 filters the container to include only images that are between 1 MB and 4 MB in size.

You can sort the results of this operation by using the sort_key and sort_dir parameters. The API uses the natural sorting of whatever image attribute is provided as the sort_key.

Note

Public images may reach end-of-life and be removed from the base image list. The Hidden Base Images article lists images which have been removed from the base images list but which may still be available.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
404	Not Found	Resource not found.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the query parameters for the request:

Name	Type	Description
limit	String	Requests a specific page size. Expect a response to a limited request to return between zero items and the number specified. The typical pattern for using the `limit` and `marker` parameters is to make an initial limited request and then to use the ID of the last image from the response as the `marker` parameter in a subsequent limited request.
marker	String	Specifies the ID of the last-seen image. The typical pattern for using the `limit` and `marker` parameters is to make an initial limited request and then to use the ID of the last image from the response as the `marker` parameter in a subsequent limited request.
name	String	Filter parameter that specifies the name of the image as a string.
visibility	String	Filter parameter that specifies image visibility as either `public`, `private`, or `shared`.
member_status	String	Filter parameter that shows images with the specified member status for only those images shared with the user. Valid values are `accepted`, `pending`, `rejected`, and `all`. The default is `accepted`.
owner		Filter parameter that shows images shared with the user by the specified tag.
tag	String	Filter parameter that shows images with the specified tag, where the owner is indicated by tenant ID.
status	String	Filter parameter that species the image status as `queued`, `saving`, `active`, `killed`, `deleted`, or `pending_delete`.
size_min	String	Filter parameter that specifies the minimum size of the image in bytes.
size_max	String	Filter parameter that specifies the maximum size of the image in bytes.
sort_key	String	Sort key. Results will be sorted by the requested image property. Accepted values are `name`, `status`, `container_format`, `disk_format`, `size`, `id`, `created_at`, and `updated_at`. The default is `created_at`.
sort_dir	String	Sort direction. Valid values are `asc` (ascending) and `desc` (descending). The default is `desc`.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
images.[]	Array	The array of the images in the list.
images.id	String	The UUID of the image.
images.name	String	The name of the image.
images.status	String	The status of the image. For possible image statuses, see Statuses.
images.visibility	String	Specifies image visibility as either `public`, `private`, or `shared`.
images.size	Integer	The size of the image in bytes.
images.checksum	String	The checksum of the image.
images.tags	String	The user-defined image tags.
images.created_at	String	The date and time that the image was created.
images.updated_at	String	The date and time that the image was updated.
images.self	String	The link to the image.
images.file	String	The image file.
images.schema	String	The schema of the image.
first	String	The URI for the first image in the list.
next	String	The URI for the next image in the list.
schema	String	The schema of the images list.

Example List images: JSON response

{
   "images":
   [
      {
         "id":"da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
         "name":"cirros-0.3.0-x86_64-uec-ramdisk",
         "status":"active",
         "visibility":"public",
         "size":2254249,
         "checksum":"2cec138d7dae2aa59038ef8c9aec2390",
         "tags":[
            "ping",
            "pong"
         ],
         "created_at":"2012-08-10T19:23:50Z",
         "updated_at":"2012-08-10T19:23:50Z",
         "self":"/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
         "file":"/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
         "schema":"/v2/schemas/image"},
      {
         "id":"0d5bcbc7-b066-4217-83f4-7111a60a399a",
         "name":"cirros-0.3.0-x86_64-uec",
         "status":"active",
         "visibility":"public",
         "size":25165824,
         "checksum":"2f81976cae15c16ef0010c51e3a6c163",
         "tags":[ ],
         "created_at":"2012-08-10T19:23:50Z",
         "updated_at":"2012-08-10T19:23:50Z",
         "self":"/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a",
         "file":"/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a/file",
         "schema":"/v2/schemas/image"},
      {
         "id":"e6421c88-b1ed-4407-8824-b57298249091",
         "name":"cirros-0.3.0-x86_64-uec-kernel",
         "status":"active",
         "visibility":"public",
         "size":4731440,
         "checksum":"cfb203e7267a28e435dbcb05af5910a9",
         "tags":[ ],
         "created_at":"2012-08-10T19:23:49Z",
         "updated_at":"2012-08-10T19:23:49Z",
         "self":"/v2/images/e6421c88-b1ed-4407-8824-b57298249091",
         "file":"/v2/images/e6421c88-b1ed-4407-8824-b57298249091/file",
         "schema":"/v2/schemas/image"}
   ],
   "first":"/v2/images?limit=3",
   "next":"/v2/images?limit=3&marker=e6421c88-b1ed-4407-8824-b57298249091",
   "schema":"/v2/schemas/images"
}

Get image details#

GET /images/{image_id}

This operation shows the details for the image. The response body is a single image entity and conforms to the schema found in Get image schema.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
404	Not Found	Resource not found.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{image_id}	UUID	Image ID stored through the image API, typically a UUID.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
id	String	The UUID of the image.
name	String	The name of the image.
status	String	The status of the image. For possible image statuses, see Image statuses
visibility	String `public`,	Specifies image visibility as either `private`, or `shared`.
checksum	String	The checksum of the image.
minRam	String	The minimum server RAM required for this image.
minDisk	String	The minimum server disk size required for this image.
tags	Array	An array of user-defined image tags.
created	String	The date and time that the image was created.
updated	String	The date and time that the image was updated.
schema	String	The schema of the image.

Example Get image details: JSON response

{
   "container_format": "ovf",
   "min_ram": 512,
   "updated_at": "2015-03-09T19:32:29Z",
   "owner": "657197",
   "file": "/v2/images/126a6674-6308-421f-801e-fc302ab4f53f/file",
   "flavor_classes": "*,!onmetal",
   "vm_mode": "hvm",
   "id": "126a6674-6308-421f-801e-fc302ab4f53f",
   "size": 758777106,
   "os_distro": "centos",
   "image_type": "base",
   "self": "/v2/images/126a6674-6308-421f-801e-fc302ab4f53f",
   "disk_format": "vhd",
   "schema": "/v2/schemas/image",
   "status": "active",
   "tags": [],
   "visibility": "public",
   "auto_disk_config": "disabled",
   "min_disk": 20,
   "name": "CentOS 7 (PVHVM)",
   "checksum": "554bd2ad5b3a275c46b6d8983ae4da26",
   "created_at": "2015-01-28T19:31:37Z",
   "cache_in_nova": "True",
   "protected": false,
   "os_type": "linux",
   "com.rackspace__1__release_id": "220",
   "com.rackspace__1__build_core": "1",
   "com.rackspace__1__options": "0",
   "com.rackspace__1__release_version": "10",
    "com.rackspace__1__platform_target": "PublicCloud",
   "com.rackspace__1__build_managed": "1",
   "com.rackspace__1__visible_managed": "0",
   "com.rackspace__1__source": "kickstart",
   "com.rackspace__1__ui_default_show": "True",
   "com.rackspace__1__release_build_date": "2015-01-28_18-59-30",
   "com.rackspace__1__visible_core": "0",
   "com.rackspace__1__build_rackconnect": "1",
   "com.rackspace__1__visible_rackconnect": "0",
   "org.openstack__1__os_version": "7",
   "org.openstack__1__architecture": "x64",
    "org.openstack__1__os_distro": "org.centos"
}

Update image#

PATCH /images/{image_id}

Updates the specified image.

This operation allows you to update an image that you own. The request body must conform to the 'application/openstack-images-v2.1-json-patch' media type. The response conforms to the schema found in Get image schema.

You can use the HTTP PATCH method to update certain standard properties, and to add, update, or remove custom, user-defined image properties. For more information, see HTTP PATCH method. Here are some guidelines for custom, user-defined properties.

Adding properties: You can add custom properties to your image.

Naming properties: We recommend you name a custom property by prefixing your domain or name, and we do not allow you to use com.rackspace as the prefix. For example, com.mycompany.myproperty and myname.myproperty are valid, and com.rackspace.myproperty is not allowed.

Do not use the prefix org.openstack since OpenStack might add a property with the same name.
Deleting properties: You can delete any custom property which you previously added to your image.
Updating properties: You can update any custom properties that you previously added to an image that you own, and you can update the following standard properties:
- name
- tags
- os_distro
- os_version
- protected
- container_format (changing this may render your image unusable)
- disk_format (changing this may render your image unusable)
- min_disk (changing this affects what flavors you use with the image)
- min_ram (changing this affects what flavors you use with the image)
- ramdisk_id (only applies to disk_format of ami )
- kernel_id (only applies to disk_format of ami )

In general, you can update any properties you own, but do not expect to be able to update anyone else’s properties. For example, you can’t update any properties starting with com.rackspace, and you might not be able to update some properties starting with org.openstack.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
415	Bad Media Type	Bad media type. This may result if the wrong media type is used in the cURL request.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{image_id}	UUID	Image ID stored through the image API, typically a UUID.

This table shows the body parameters for the request:

Name	Type	Description
op	String (Required)	The operation to be executed ( `add`, `remove`, or `replace` ).
path	String (Required)	The location within the image where the operation is to be performed.
value	String	The actual value to be added or replaced. It is not required for the `delete` operation.

Example Update image: JSON request

The following example updates two properties for the image: name and tag.

Tip

Like all Images API calls, the Image Update operation requires the Content-Type header to match the media type used for the body of the request. If this header is missing or does not match a supported media type, the call results in a 415 error. Don’t forget that the Content-type for the Image Update operation must be the appropriate media-type descriptor for the HTTP Patch method (see HTTP PATCH method). For example: Content-Type: application/openstack-images-v2.1-json-patch.

[
    {"op": "replace", "path": "/name", "value": "Fedora 17"},
    {"op": "replace", "path": "/tags", "value": ["fedora", "beefy"]}
]

Response#

This table shows the body parameters for the response:

Name	Type	Description
id	String	The UUID of the image.
name	String	The name of the image.
status	String	The status of the image. For possible image statuses, see Image statuses
visibility	String	Specifies image visibility as either `public`, `private`, or `shared`.
checksum	String	The checksum of the image.
minRam	String	The minimum server RAM required for this image.
minDisk	String	The minimum server disk size required for this image.
tags[]	Array	An array of user-defined image tags.
created	String	The date and time that the image was created.
updated	String	The date and time that the image was updated.
schema	String	The schema of the image.

Example Update image: JSON response

{
   "id":"e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
   "name":"Fedora 17",
   "status":"queued",
   "visibility":"public",
   "tags": ["fedora", "beefy"],
   "created_at":"2012-08-11T17:15:52Z",
   "updated_at":"2012-08-11T17:15:52Z",
   "self":"/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
   "file":"/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/file",
   "schema":"/v2/schemas/image"
}

Delete image#

DELETE /images/{image_id}

This operation deletes the image. Make sure you set protected parameter to false (Boolean) before performing the delete. If the operation succeeds, it returns an HTTP 204 status code with no response body.

Warning

An attempt to delete an image with the protected parameter set to true (boolean) results in a response code HTTP 403.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Delete Successful	Delete request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
404	Not Found	Resource not found.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{image_id}	UUID	Image ID stored through the image API, typically a UUID.

This operation does not accept a request body.

Response#

This operation does not return a response body.