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.

This table shows the possible response codes for this operation:

{
   "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:

{
   "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:

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

{
   "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.

This table shows the possible response codes for this operation: