Image Service API v2 (SUPPORTED)

Image Service API v2.0, API v2.1, and API v2.2.

Cloud providers can configure property protections that prevent non-administrative users from updating and deleting protected properties. For more information, see Image property protection in the OpenStack Cloud Administrator Guide .

API versions

GET
/
List API versions

Lists information about all Image Service API versions.

 
Normal response codes
200, 300
{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v2.2",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.1",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "id": "v1.1",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v1/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

Images

Create, update, and delete image metadata records. Enable users to share images with each other.

POST
/v2/images
Create image

Creates a virtual machine (VM) image. (Since Image API v2.0.)

 

Created with a Location header that contains the newly-created URI for the image. Response body represents the created image entity.

Synchronous Postconditions

  • With correct permissions, you can see the image status as queued through API calls.

  • With correct permissions, you can see the image status as active through API calls if you created the image with Location header.

Normal response codes
201
Request parameters
Parameter Style Type Description
name plain xsd:string

Name for the image. The name of an image is not unique to a Image Service node. The API cannot expect users to know the names of images owned by others.

id (Optional) plain csapi:uuid

The image ID.

visibility (Optional) plain xsd:string

Image visibility. Public or private. Default is public.

tags (Optional) plain xsd:dict

Image tags.

container_format (Optional) plain xsd:string

Format of the container.

disk_format (Optional) plain xsd:string

Format of the disk.

min_disk (Optional) plain xsd:int

Amount of disk space (in GB) required to boot image.

min_ram (Optional) plain xsd:int

Amount of RAM (in MB) required to boot image.

protected (Optional) plain xsd:bool

If true, image is not deletable.

properties (Optional) plain xsd:dict

Properties, if any, that are associated with the image.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

container_format plain xsd:string

The container format of image. Valid values are ami, ari, aki, bare, and ovf.

min_ram plain csapi:uuid

The minimum amount of RAM required to boot the image, in MBs.

updated_at plain xsd:datetime

The date and time when the image was last updated.

owner plain xsd:string

The ID of the owner, or tenant, of the image.

min_disk plain xsd:int

The minimum disk size required to boot the image, in GBs.

tag URI xsd:string

Image tag.

visibility plain xsd:boolean

The image visibility.

id plain csapi:uuid

The unique ID for the image.

size plain xsd:int

The size of the image data, in bytes.

virtual_size plain xsd:int

The virtual size of the image.

name plain xsd:string

The name of the image.

checksum plain xsd:string

Hash of the image data used. The Image Service uses this value for verification.

created_at plain xsd:datetime

The date and time when the image was created.

disk_format plain xsd:string

The disk format of the image. Valid values are ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.

properties plain xsd:dict

Properties, if any, that are associated with the image.

protected plain xsd:boolean

Defines whether the image can be deleted.

location header xsd:string

URL to access the image file kept in external store.

self plain xsd:string

URL for the virtual machine image.

file plain xsd:string

URL for the virtual machine image file.

schema plain xsd:string

URL for schema of the virtual machine image.

{
    "id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
    "name": "Ubuntu 12.10",
    "tags": [
        "ubuntu",
        "quantal"
    ]
}
{
    "status": "queued",
    "name": "test-001",
    "tags": [],
    "container_format": "bare",
    "created_at": "2014-11-11T20:47:55Z",
    "disk_format": "qcow2",
    "updated_at": "2014-11-11T20:47:55Z",
    "visibility": "private",
    "self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565ca",
    "min_disk": 0,
    "protected": false,
    "id": "b2173dd3-7ad6-4362-baa6-a68bce3565ca",
    "file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565ca/file",
    "owner": "b4eedccc6fb74fa8a7ad6b08382b852b",
    "min_ram": 0,
    "schema": "/v2/schemas/image"
}
GET
/v2/images
List images

Lists public virtual machine (VM) images. (Since Image API v2.0.)

 

Returns a subset of the larger collection of images and a link that you can use to get the next set of images. You should always check for the presence of a next link and use it as the URI in a subsequent HTTP GET request. You should 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 operation accepts several types of query parameters that let you filter the results of the returned collection.

A client can provide direct comparison filters 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 and 4 MB.

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.

You can see a list of VM images which status is in active, queued, or saving

Normal response codes
200
Request parameters
Parameter Style Type Description
limit (Optional) query xsd:int

Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker (Optional) query xsd:string

Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

name (Optional) query xsd:string

Filter parameter. Name of the image as a string.

visibility (Optional) query imageapi:string

Filter parameter. Image visibility. Valid values are public, private, and shared. Default is public, private, and shared images with accepted member status.

member_status (Optional) query imageapi:string

Filter parameter. Only show images with the specified member status. Valid values are accepted, pending, rejected, and all. Default is accepted.

owner (Optional) query imageapi:string

Filter parameter. Shows images shared with me by the specified owner, where the owner is indicated by tenant ID.

status (Optional) query xsd:int

Filter parameter. The image status, such as queued, saving, active, killed, deleted, and pending_delete.

size_min (Optional) query xsd:string

Filter parameter. Value of the minimum size of the image in bytes.

size_max (Optional) query xsd:string

Filter parameter. Value of the maximum size of the image in bytes.

sort_key (Optional) query xsd:string

Sort key. All image attributes can be used as the sort_key, except tags and link attributes. Default is created_at.

sort_dir (Optional) query xsd:string

Sort direction. Valid values are asc (ascending) and desc (descending). Default is desc.

tag (Optional) query xsd:string

Image tag. For example, ?tag="cirros".

Response parameters
Parameter Style Type Description
images plain xsd:string

An images object.

status plain xsd:string

The image status.

name plain xsd:string

The name of the image.

tag URI xsd:string

Image tag.

container_format plain xsd:string

The container format of image. Valid values are ami, ari, aki, bare, and ovf.

created_at plain xsd:datetime

The date and time when the image was created.

disk_format plain xsd:string

The disk format of the image. Valid values are ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.

updated_at plain xsd:datetime

The date and time when the image was last updated.

min_disk plain xsd:int

The minimum disk size required to boot the image, in GBs.

protected plain xsd:boolean

Defines whether the image can be deleted.

id plain csapi:uuid

The unique ID for the image.

min_ram plain csapi:uuid

The minimum amount of RAM required to boot the image, in MBs.

checksum plain xsd:string

Hash of the image data used. The Image Service uses this value for verification.

owner plain xsd:string

The ID of the owner, or tenant, of the image.

visibility plain xsd:boolean

The image visibility.

virtual_size plain xsd:int

The virtual size of the image.

size plain xsd:int

The size of the image data, in bytes.

properties plain xsd:dict

Properties, if any, that are associated with the image.

url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

metadata plain xsd:dict

The location metadata.

direct_url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

self plain xsd:string

URL for the virtual machine image.

file plain xsd:string

URL for the virtual machine image file.

schema plain xsd:string

URL for schema of the virtual machine image.

schema plain xsd:string

URL for schema of the virtual machine images.

first plain xsd:string

URL for the first page of response.

{
    "images": [
        {
            "status": "active",
            "name": "cirros-0.3.2-x86_64-disk",
            "tags": [],
            "container_format": "bare",
            "created_at": "2014-11-07T17:07:06Z",
            "disk_format": "qcow2",
            "updated_at": "2014-11-07T17:19:09Z",
            "visibility": "public",
            "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
            "min_disk": 0,
            "protected": false,
            "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
            "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
            "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
            "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
            "size": 13167616,
            "min_ram": 0,
            "schema": "/v2/schemas/image"
        },
        {
            "status": "active",
            "name": "F17-x86_64-cfntools",
            "tags": [],
            "container_format": "bare",
            "created_at": "2014-10-30T08:23:39Z",
            "disk_format": "qcow2",
            "updated_at": "2014-11-03T16:40:10Z",
            "visibility": "public",
            "self": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c",
            "min_disk": 0,
            "protected": false,
            "id": "781b3762-9469-4cec-b58d-3349e5de4e9c",
            "file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file",
            "checksum": "afab0f79bac770d61d24b4d0560b5f70",
            "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
            "size": 476704768,
            "min_ram": 0,
            "schema": "/v2/schemas/image"
        }
    ],
    "schema": "/v2/schemas/images",
    "first": "/v2/images"
}
GET
/v2/images/​{image_id}​
Get image details

Gets details for a specified image. (Since Image API v2.0.)

 

Response body is a single image entity.

Preconditions

  • The specified image must exist.

Normal response codes
200
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

name plain xsd:string

The name of the image.

tag URI xsd:string

Image tag.

container_format plain xsd:string

The container format of image. Valid values are ami, ari, aki, bare, and ovf.

created_at plain xsd:datetime

The date and time when the image was created.

disk_format plain xsd:string

The disk format of the image. Valid values are ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.

updated_at plain xsd:datetime

The date and time when the image was last updated.

min_disk plain xsd:int

The minimum disk size required to boot the image, in GBs.

protected plain xsd:boolean

Defines whether the image can be deleted.

id plain csapi:uuid

The unique ID for the image.

min_ram plain csapi:uuid

The minimum amount of RAM required to boot the image, in MBs.

checksum plain xsd:string

Hash of the image data used. The Image Service uses this value for verification.

owner plain xsd:string

The ID of the owner, or tenant, of the image.

visibility plain xsd:boolean

The image visibility.

size plain xsd:int

The size of the image data, in bytes.

url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

metadata plain xsd:dict

The location metadata.

properties plain xsd:dict

Properties, if any, that are associated with the image.

direct_url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

self plain xsd:string

URL for the virtual machine image.

file plain xsd:string

URL for the virtual machine image file.

schema plain xsd:string

URL for schema of the virtual machine image.

{
    "status": "active",
    "name": "cirros-0.3.2-x86_64-disk",
    "tags": [],
    "container_format": "bare",
    "created_at": "2014-05-05T17:15:10Z",
    "disk_format": "qcow2",
    "updated_at": "2014-05-05T17:15:11Z",
    "visibility": "public",
    "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
    "min_disk": 0,
    "protected": false,
    "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
    "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
    "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
    "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
    "size": 13167616,
    "min_ram": 0,
    "schema": "/v2/schemas/image"
}
PATCH
/v2/images/​{image_id}​
Update image

Updates a specified image. (Since Image API v2.0.)

 

Request body must conform to one of the following media types:

  • application/openstack-images-v2.0-json-patch

  • application/openstack-images-v2.1-json-patch (Since Image API v2.2)

You can also use the PATCH method to add or remove image properties.

For information about the PATCH method and the available media types, see Appendix B: HTTP PATCH media types in the OpenStack Image Service API v2 Reference .

Preconditions

  • When adding or replacing a new location to the specified image, you need to set disk_format and container_format in the image.

  • When locations of the specified image is replaced by replacing operation, the old location needs to be set in the image on ahead.

Synchronous Postconditions

  • With correct permissions, you can see the updated values of the image's attributes.

  • With correct permissions, you can see the image status as active through API calls after adding a location to the image which had no location.

  • With correct permissions, you can see the image status as queued through API calls after removing all locations from the image

Troubleshooting

  • If you can not update locations you might lack some infomation in your requests. Ensure you meet the preconditions then investigate the your API requests.

Normal response codes
200
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

path plain xsd:string

Image's property.

value plain xsd:string

Value of image property used in add or replace operations expressed in JSON notation. For example, you must enclose strings in quotation marks, and you do not enclose numeric values in quotation marks.

op plain xsd:string

The operation. Valid values are:

add: adds a new property or location in the specified image.

remove: removes the specified image's property or location.

replace: replaces the value of a specified image's property or location.

url plain xsd:string

URL to access the image file kept in external store.

metadata plain xsd:dict

The location metadata.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

name plain xsd:string

The name of the image.

tag URI xsd:string

Image tag.

container_format plain xsd:string

The container format of image. Valid values are ami, ari, aki, bare, and ovf.

created_at plain xsd:datetime

The date and time when the image was created.

disk_format plain xsd:string

The disk format of the image. Valid values are ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.

updated_at plain xsd:datetime

The date and time when the image was last updated.

min_disk plain xsd:int

The minimum disk size required to boot the image, in GBs.

protected plain xsd:boolean

Defines whether the image can be deleted.

id plain csapi:uuid

The unique ID for the image.

min_ram plain csapi:uuid

The minimum amount of RAM required to boot the image, in MBs.

checksum plain xsd:string

Hash of the image data used. The Image Service uses this value for verification.

owner plain xsd:string

The ID of the owner, or tenant, of the image.

visibility plain xsd:boolean

The image visibility.

size plain xsd:int

The size of the image data, in bytes.

url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

metadata plain xsd:dict

The location metadata.

properties plain xsd:dict

Properties, if any, that are associated with the image.

direct_url plain xsd:string

URL to access the image file kept in external store. It appears when you set the show_multiple_locations option to True in the Image service's configuration file.

self plain xsd:string

URL for the virtual machine image.

file plain xsd:string

URL for the virtual machine image file.

schema plain xsd:string

URL for schema of the virtual machine image.

[
    {
        "op": "replace",
        "path": "/name",
        "value": "Fedora 17"
    },
    {
        "op": "replace",
        "path": "/tags",
        "value": [
            "fedora",
            "beefy"
        ]
    }
]
{
    "id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
    "name": "Fedora 17",
    "status": "active",
    "visibility": "public",
    "size": 2254249,
    "checksum": "2cec138d7dae2aa59038ef8c9aec2390",
    "tags": [
        "fedora",
        "beefy"
    ],
    "created_at": "2012-08-10T19:23:50Z",
    "updated_at": "2012-08-12T11:11:33Z",
    "self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
    "file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
    "schema": "/v2/schemas/image"
}
DELETE
/v2/images/​{image_id}​
Delete image

Deletes a specified image. (Since Image API v2.0.)

 

You cannot delete images with the 'protected' attribute set to true (boolean);

Preconditions

  • You can delete an image in all status except deleted.

  • You must first set the 'protected' attribute to false (boolean) and then perform the delete.

Synchronous Postconditions

  • The response is empty and returns the HTTP 204 status code.

  • The image is deleted in images index.

  • The binary image data managed by OpenStack Image Service is deleted from the storage node if the deleted image stores image data in the node.

TroubleShooting

  • The response returns the HTTP 403 status code when the 'protected' attribute is set to true even if you have a correct permissions. Ensure you meet the preconditions then investigate the attribute.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

This operation does not return a response body.

Image data

Upload and download raw image data.

PUT
/v2/images/​{image_id}​/file
Upload binary image data

Uploads binary image data. (Since Image API v2.0.)

 

Set the Content-Type request header to application/octet-stream.

Example call: curl -i -X PUT -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -d @/home/glance/ubuntu-12.10.qcow2 $image_url/v2/images/{image_id}/file

Preconditions

  • The specified image must exist before you store binary image data.

  • You need to set disk_format and container_format in the image before you store the data.

  • You can only store the data into a image which status is queued.

  • The user must have enough image strage quota remaining to store the data.

  • Size of the data must be less than OpenStack Image Service restricts.

Synchronous Postconditions

  • With correct permissions, you can see the image status as active via API calls.

  • With correct access, you can see the stored data in the storage system that OpenStack Image Service manages.

Troubleshooting

  • If you can not store the data you might lack some infomation in your requests or exceed the quota you are allowed to use. Ensure you meet the preconditions then investigate the your API requests.

  • The storage backends for storing the data need enough free storage space to match the size of the data.

Normal response codes
204
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

This operation does not return a response body.

GET
/v2/images/​{image_id}​/file
Download binary image data

Downloads binary image data. (Since Image API v2.0.)

 

Example call: curl -i -X GET -H "X-Auth-Token: $token" $image_url/v2/images/{image_id}/file

The response body contains the raw binary data that represents the actual virtual disk. The Content-Type header contains the value application/octet-stream. The Content-MD5 header contains an MD5 checksum of the image data. Clients are encouraged to verify the integrity of the image data they receive by using this checksum.

Preconditions

  • The specified images must exist.

Synchronous Postconditions

  • You can download the binary image data in your machine if the specified image has image data.

  • If image data exists, you receive the HTTP 200 status code.

  • If no image data exists, you receive the HTTP 204 status code.

Normal response codes
200, 204
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

This operation does not return a response body.

Image tags

Add and delete image tags.

PUT
/v2/images/​{image_id}​/tags/​{tag}​
Add image tag

Adds a specified tag to a specified image. (Since Image API v2.0.)

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tag URI xsd:string

Image tag.

image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

tag URI xsd:string

Image tag.

This operation does not return a response body.

DELETE
/v2/images/​{image_id}​/tags/​{tag}​
Delete image tag

Deletes a specified tag from a specified image. (Since Image API v2.0.)

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tag URI xsd:string

Image tag.

image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

tag URI xsd:string

Image tag.

This operation does not return a response body.

Members

POST
/v2/images/​{image_id}​/members
Create image member

Adds a specified tenant ID as an image member. (Since Image API v2.1.)

 

Preconditions

  • The specified images must exist.

  • You can only add a new member to an image which 'visibility' attribute is private.

  • You need to be the owner of the specified image.

Synchronous Postconditions

  • With correct permissions, you can see the member status of the image as pending through API calls.

Troubleshooting

  • Even if you have correct permissions, if the 'visibility' attribute is set to public, the request returns the HTTP 403 status code. Ensure you meet the preconditions then investigate the attribute.

  • If the member in the request is already a member for the image, the service returns the HTTP 409 "Conflict" status code in case you meant a different member. Double-check the member to ensure you want it to be a member of the image.

Normal response codes
200
Error response codes
invalidVisibility (403), memberConflict (409)
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

member_id URI xsd:string

Image member ID. For example, the tenant ID of the user with whom the image is being shared.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of this image member.

created_at plain xsd:datetime

Date and time of image member creation in the following format: YYYY-MM-DDThh:zz:ssZ.

updated_at plain xsd:datetime

Date and time of last modification of image member in the following format: YYYY-MM-DDThh:zz:ssZ.

image_id plain csapi:uuid

An identifier for the image.

member_id plain xsd:string

The image member ID. For example, the tenant ID of the user with whom the image is being shared.

schema plain xsd:string

The URL for schema of the member.

{
    "member": "8989447062e04a818baf9e073fd04fa7"
}
{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "pending",
    "updated_at": "2013-09-20T19:25:31Z"
}
GET
/v2/images/​{image_id}​/members
List image members

Lists the tenants with whom this image has been shared. (Since Image API v2.1.)

 

If a user with whom this image is shared makes this call, the member list contains only information for that user.

If a user with whom this image has not been shared makes this call, the call returns the HTTP 404 status code.

Preconditions

  • The specified image must exist.

  • You need to be the owner or a member of the specified image.

Normal response codes
200
Error response codes
404
Request parameters
Parameter Style Type Description
image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of this image member.

created_at plain xsd:datetime

Date and time of image member creation in the following format: YYYY-MM-DDThh:zz:ssZ.

updated_at plain xsd:datetime

Date and time of last modification of image member in the following format: YYYY-MM-DDThh:zz:ssZ.

image_id plain csapi:uuid

An identifier for the image.

member_id plain xsd:string

The image member ID. For example, the tenant ID of the user with whom the image is being shared.

schema plain xsd:string

The URL for schema of the member.

schema plain xsd:string

The URL for schema of the members.

{
    "members": [
        {
            "created_at": "2013-10-07T17:58:03Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "123456789",
            "schema": "/v2/schemas/member",
            "status": "pending",
            "updated_at": "2013-10-07T17:58:03Z"
        },
        {
            "created_at": "2013-10-07T17:58:55Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "987654321",
            "schema": "/v2/schemas/member",
            "status": "accepted",
            "updated_at": "2013-10-08T12:08:55Z"
        }
    ],
    "schema": "/v2/schemas/members"
}
GET
/v2/images/​{image_id}​/members/​{member_id}​
Show image member details

Shows image member details.

 

Response body is a single image member entity. (Since Image API 2.2.)

Preconditions

  • The specified image must exist.

  • You need to be the owner or a member of the specified image.

Normal response codes
200
Request parameters
Parameter Style Type Description
member_id URI xsd:string

Image member ID. For example, the tenant ID of the user with whom the image is being shared.

image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of this image member.

created_at plain xsd:datetime

Date and time of image member creation in the following format: YYYY-MM-DDThh:zz:ssZ.

updated_at plain xsd:datetime

Date and time of last modification of image member in the following format: YYYY-MM-DDThh:zz:ssZ.

image_id plain csapi:uuid

An identifier for the image.

member_id plain xsd:string

The image member ID. For example, the tenant ID of the user with whom the image is being shared.

schema plain xsd:string

The URL for schema of the member.

{
    "status": "pending",
    "created_at": "2013-11-26T07:21:21Z",
    "updated_at": "2013-11-26T07:21:21Z",
    "image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member"
}
DELETE
/v2/images/​{image_id}​/members/​{member_id}​
Delete image member

Deletes a specified tenant ID from the member list of the specified image. (Since Image API v2.1.)

 

Preconditions

  • The specified image must exist.

  • You need to be the owner of the specified image.

Synchronous Postconditions

  • The specified member is removed from the image members.

Troubleshooting

  • Even if you have correct permissions, it you are not the owner of the specified image, the request returns the HTTP 403 status code. Ensure you meet the preconditions then investigate the attribute.

Normal response codes
204
Error response codes
forbidden (403)
Request parameters
Parameter Style Type Description
member_id URI xsd:string

Image member ID. For example, the tenant ID of the user with whom the image is being shared.

image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

This operation does not return a response body.

PUT
/v2/images/​{image_id}​/members/​{member_id}​
Update image member

Sets the specified status for the specified member of the specified image. (Since Image API v2.1.)

 

Preconditions

  • The specified images must exist.

  • You need to be a member of the specified image.

Synchronous Postconditions

  • If you update the member status to accepted, and have the correct permissions, you will see the image in responses of List Images API call.

  • With correct permissions, you can see the updated member status of the image through API calls.

Normal response codes
200
Request parameters
Parameter Style Type Description
member_id URI xsd:string

Image member ID. For example, the tenant ID of the user with whom the image is being shared.

image_id URI csapi:uuid

Image ID stored through the image API. Typically a UUID.

status plain xsd:string

The status of this image member.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of this image member.

created_at plain xsd:datetime

Date and time of image member creation in the following format: YYYY-MM-DDThh:zz:ssZ.

updated_at plain xsd:datetime

Date and time of last modification of image member in the following format: YYYY-MM-DDThh:zz:ssZ.

image_id plain csapi:uuid

An identifier for the image.

member_id plain xsd:string

The image member ID. For example, the tenant ID of the user with whom the image is being shared.

schema plain xsd:string

The URL for schema of the member.

{
    "status": "accepted"
}
{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "accepted",
    "updated_at": "2013-09-20T20:15:31Z"
}

Image schemas

Get a JSON-schema document that represents an images or image entity.

GET
/v2/schemas/images
Get images schema

Gets a json-schema document that represents an images entity. (Since Images v2.0.)

 

An images entity is a container of image entities.

The following schema is solely an example. Consider only the response to the API call as authoritative.

Normal response codes
200
{
    "name": "images",
    "properties": {
        "first": {
            "type": "string"
        },
        "images": {
            "items": {
                "name": "image",
                "properties": {
                    "architecture": {
                        "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
                        "type": "string"
                    },
                    "checksum": {
                        "description": "md5 hash of image contents. (READ-ONLY)",
                        "maxLength": 32,
                        "type": "string"
                    },
                    "container_format": {
                        "description": "Format of the container",
                        "enum": [
                            "ami",
                            "ari",
                            "aki",
                            "bare",
                            "ovf"
                        ],
                        "type": "string"
                    },
                    "created_at": {
                        "description": "Date and time of image registration (READ-ONLY)",
                        "type": "string"
                    },
                    "direct_url": {
                        "description": "URL to access the image file kept in external store (READ-ONLY)",
                        "type": "string"
                    },
                    "disk_format": {
                        "description": "Format of the disk",
                        "enum": [
                            "ami",
                            "ari",
                            "aki",
                            "vhd",
                            "vmdk",
                            "raw",
                            "qcow2",
                            "vdi",
                            "iso"
                        ],
                        "type": "string"
                    },
                    "file": {
                        "description": "(READ-ONLY)",
                        "type": "string"
                    },
                    "id": {
                        "description": "An identifier for the image",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "instance_uuid": {
                        "description": "ID of instance used to create this image.",
                        "type": "string"
                    },
                    "kernel_id": {
                        "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "locations": {
                        "description": "A set of URLs to access the image file kept in external store",
                        "items": {
                            "properties": {
                                "metadata": {
                                    "type": "object"
                                },
                                "url": {
                                    "maxLength": 255,
                                    "type": "string"
                                }
                            },
                            "required": [
                                "url",
                                "metadata"
                            ],
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "min_disk": {
                        "description": "Amount of disk space (in GB) required to boot image.",
                        "type": "integer"
                    },
                    "min_ram": {
                        "description": "Amount of ram (in MB) required to boot image.",
                        "type": "integer"
                    },
                    "name": {
                        "description": "Descriptive name for the image",
                        "maxLength": 255,
                        "type": "string"
                    },
                    "os_distro": {
                        "description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
                        "type": "string"
                    },
                    "os_version": {
                        "description": "Operating system version as specified by the distributor",
                        "type": "string"
                    },
                    "owner": {
                        "description": "Owner of the image",
                        "maxLength": 255,
                        "type": "string"
                    },
                    "protected": {
                        "description": "If true, image will not be deletable.",
                        "type": "boolean"
                    },
                    "ramdisk_id": {
                        "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "schema": {
                        "description": "(READ-ONLY)",
                        "type": "string"
                    },
                    "self": {
                        "description": "(READ-ONLY)",
                        "type": "string"
                    },
                    "size": {
                        "description": "Size of image file in bytes (READ-ONLY)",
                        "type": "integer"
                    },
                    "status": {
                        "description": "Status of the image (READ-ONLY)",
                        "enum": [
                            "queued",
                            "saving",
                            "active",
                            "killed",
                            "deleted",
                            "pending_delete"
                        ],
                        "type": "string"
                    },
                    "tags": {
                        "description": "List of strings related to the image",
                        "items": {
                            "maxLength": 255,
                            "type": "string"
                        },
                        "type": "array"
                    },
                    "updated_at": {
                        "description": "Date and time of the last image modification (READ-ONLY)",
                        "type": "string"
                    },
                    "virtual_size": {
                        "description": "Virtual size of image in bytes (READ-ONLY)",
                        "type": "integer"
                    },
                    "visibility": {
                        "description": "Scope of image accessibility",
                        "enum": [
                            "public",
                            "private"
                        ],
                        "type": "string"
                    }
                },
                "additionalProperties": {
                    "type": "string"
                },
                "links": [
                    {
                        "href": "{self}",
                        "rel": "self"
                    },
                    {
                        "href": "{file}",
                        "rel": "enclosure"
                    },
                    {
                        "href": "{schema}",
                        "rel": "describedby"
                    }
                ]
            },
            "type": "array"
        },
        "next": {
            "type": "string"
        },
        "schema": {
            "type": "string"
        }
    },
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/image
Get image schema

Gets a json-schema document that represents an image entity. (Since Images v2.0.)

 

The following schema is solely an example. Consider only the response to the API call as authoritative.

Normal response codes
200
{
    "name": "image",
    "properties": {
        "architecture": {
            "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
            "type": "string"
        },
        "checksum": {
            "description": "md5 hash of image contents. (READ-ONLY)",
            "maxLength": 32,
            "type": "string"
        },
        "container_format": {
            "description": "Format of the container",
            "enum": [
                "ami",
                "ari",
                "aki",
                "bare",
                "ovf"
            ],
            "type": "string"
        },
        "created_at": {
            "description": "Date and time of image registration (READ-ONLY)",
            "type": "string"
        },
        "direct_url": {
            "description": "URL to access the image file kept in external store (READ-ONLY)",
            "type": "string"
        },
        "disk_format": {
            "description": "Format of the disk",
            "enum": [
                "ami",
                "ari",
                "aki",
                "vhd",
                "vmdk",
                "raw",
                "qcow2",
                "vdi",
                "iso"
            ],
            "type": "string"
        },
        "file": {
            "description": "(READ-ONLY)",
            "type": "string"
        },
        "id": {
            "description": "An identifier for the image",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "instance_uuid": {
            "description": "ID of instance used to create this image.",
            "type": "string"
        },
        "kernel_id": {
            "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "locations": {
            "description": "A set of URLs to access the image file kept in external store",
            "items": {
                "properties": {
                    "metadata": {
                        "type": "object"
                    },
                    "url": {
                        "maxLength": 255,
                        "type": "string"
                    }
                },
                "required": [
                    "url",
                    "metadata"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "min_disk": {
            "description": "Amount of disk space (in GB) required to boot image.",
            "type": "integer"
        },
        "min_ram": {
            "description": "Amount of ram (in MB) required to boot image.",
            "type": "integer"
        },
        "name": {
            "description": "Descriptive name for the image",
            "maxLength": 255,
            "type": "string"
        },
        "os_distro": {
            "description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
            "type": "string"
        },
        "os_version": {
            "description": "Operating system version as specified by the distributor",
            "type": "string"
        },
        "owner": {
            "description": "Owner of the image",
            "maxLength": 255,
            "type": "string"
        },
        "protected": {
            "description": "If true, image will not be deletable.",
            "type": "boolean"
        },
        "ramdisk_id": {
            "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "schema": {
            "description": "(READ-ONLY)",
            "type": "string"
        },
        "self": {
            "description": "(READ-ONLY)",
            "type": "string"
        },
        "size": {
            "description": "Size of image file in bytes (READ-ONLY)",
            "type": "integer"
        },
        "status": {
            "description": "Status of the image (READ-ONLY)",
            "enum": [
                "queued",
                "saving",
                "active",
                "killed",
                "deleted",
                "pending_delete"
            ],
            "type": "string"
        },
        "tags": {
            "description": "List of strings related to the image",
            "items": {
                "maxLength": 255,
                "type": "string"
            },
            "type": "array"
        },
        "updated_at": {
            "description": "Date and time of the last image modification (READ-ONLY)",
            "type": "string"
        },
        "virtual_size": {
            "description": "Virtual size of image in bytes (READ-ONLY)",
            "type": "integer"
        },
        "visibility": {
            "description": "Scope of image accessibility",
            "enum": [
                "public",
                "private"
            ],
            "type": "string"
        }
    },
    "additionalProperties": {
        "type": "string"
    },
    "links": [
        {
            "href": "{self}",
            "rel": "self"
        },
        {
            "href": "{file}",
            "rel": "enclosure"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/members
Get image members schema

Gets a json-schema document that represents an image members entity. (Since Images v2.1.)

 

An image members entity is a container of image member entities.

The following schema is solely an example. Consider only the response to the API call as authoritative.

Normal response codes
200
{
    "name": "members",
    "properties": {
        "members": {
            "items": {
                "name": "member",
                "properties": {
                    "created_at": {
                        "description": "Date and time of image member creation",
                        "type": "string"
                    },
                    "image_id": {
                        "description": "An identifier for the image",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "member_id": {
                        "description": "An identifier for the image member (tenantId)",
                        "type": "string"
                    },
                    "status": {
                        "description": "The status of this image member",
                        "enum": [
                            "pending",
                            "accepted",
                            "rejected"
                        ],
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Date and time of last modification of image member",
                        "type": "string"
                    },
                    "schema": {
                        "type": "string"
                    }
                }
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        }
    },
    "links": [
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/member
Get image member schema

Gets a json-schema document that represents an image member entity. (Since Images v2.1.)

 

The following schema is solely an example. Consider only the response to the API call as authoritative.

Normal response codes
200
{
    "name": "member",
    "properties": {
        "created_at": {
            "description": "Date and time of image member creation",
            "type": "string"
        },
        "image_id": {
            "description": "An identifier for the image",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "member_id": {
            "description": "An identifier for the image member (tenantId)",
            "type": "string"
        },
        "status": {
            "description": "The status of this image member",
            "enum": [
                "pending",
                "accepted",
                "rejected"
            ],
            "type": "string"
        },
        "updated_at": {
            "description": "Date and time of last modification of image member",
            "type": "string"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.