• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
    • Solve: Thought Leadership
  • Support Documentation

Developer Docs


Let’s Build Something Powerful Together!

End-to-End Multicloud Solutions.   Solving Together.™   Learn more at Rackspace.com

Submit an issue
  • Cloud Images 2.0
  • Getting started
    • Get your credentials
    • Send API requests to Rackspace Cloud Images
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Send an authentication request
      • Review the authentication response
      • Configure environment variables
    • Concepts
      • Images
        • Standard images
        • Nonstandard images
      • Image entities
      • Image identifiers
      • Image properties
      • Image sharing
        • Sample workflow for image sharing, after image creation
      • Asynchronous tasks
        • High-level process for importing an image
        • High-level process for exporting an image
      • Statuses
        • Image statuses
        • Task statuses
        • Image member statuses
      • HTTP PATCH method
        • Restricted JSON pointers
        • Using the HTTP PATCH method
        • HTTP PATCH add operation
        • HTTP PATCH remove operation
        • HTTP PATCH replace operation
    • Use images
      • Listing images
      • Getting details for an image
      • Updating an image
      • Importing an image by using tasks
      • Exporting an image by using tasks
      • Getting details for a task
    • Share images
      • Creating an image member
      • Listing image members
      • Getting image member details
      • Updating an image member
      • Deleting an image member
  • General API information
    • Service access endpoints
    • Request and response types
      • Media Types
      • JSON Schemas
    • Paginated collections
    • Date and time format
    • Role-based access control (RBAC)
      • Assigning roles to account users
      • Roles available for Cloud Images
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Cloud Images API operations
  • API reference
    • Images
      • List images
        • Request
        • Response
      • Get image details
        • Request
        • Response
      • Update image
        • Request
        • Response
      • Delete image
        • Request
        • Response
    • Image sharing
      • List image members
        • Request
        • Response
      • Get image member details
        • Request
        • Response
      • Create image member
        • Request
        • Response
      • Delete image member
        • Request
        • Response
      • Update image member
        • Request
        • Response
    • Image tag
      • Add image tag
        • Request
        • Response
      • Delete image tag
        • Request
        • Response
    • Image task
      • List tasks
        • Request
        • Response
      • Get task details
        • Request
        • Response
      • Task to import image
        • Request
        • Response
      • Task to export image
        • Request
        • Response
    • JSON schemas
      • Get images schema
        • Request
        • Response
      • Get image schema
        • Request
        • Response
      • Get image members schema
        • Request
        • Response
      • Get image member schema
        • Request
        • Response
      • Get task schema
        • Request
        • Response
      • Get tasks schema
        • Request
        • Response
  • Glossary
  • Release Notes
    • API v2.0 release, September 9, 2013
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

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.

Previous API reference
Next Image sharing
Developer Network
  • Developer Center
  • API Documentation and User Guides
  • SDKs
  • Rackspace How-To
Blogs
  • Technical Blog
  • Rackspace Blog
  • Solve: Thought Leadership
Other Information
  • Customer Stories
  • Events
  • Programs
  • Careers
  • Style Guide for Technical Content
©2020 Rackspace US, Inc.
  • ©2020 Rackspace US, Inc.
  • About Rackspace
  • Privacy Statement
  • Website Terms
  • Trademarks