Image service API v2 (CURRENT)

Image service API v2.0, API v2.1, API v2.2, and API v2.3.

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 version information for all Image service API versions.

 
Normal response codes
300
{
    "versions": [
        {
            "status": "EXPERIMENTAL",
            "id": "v3.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v3/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "id": "v2.3",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "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": "SUPPORTED",
            "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 and does not return a response body.

Images (images)

Creates, lists, updates, and deletes images.

Image operations show all fields in the response body. Any field with no value is set to null value (JSON null data type).

The possible status values for images are:

Image status
Status Description

queued

The Image service reserved an image ID for the image in the registry but did not yet upload any image data.

saving

The Image service is currently uploading the raw data for the image.

active

The image is active and fully available in the Image service.

killed

An image data upload error occurred.

deleted

The Image service retains information about the image but the image is no longer available for use.

pending_delete

Similar to the deleted status. An image in this state is not recoverable.

GET
/v2/images
List images

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

 

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 query parameters to filter the response.

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

You can use the size_min and size_max query parameters to filter images that are greater than or less than the image size. The size, in bytes, is the size of an image on disk.

For example, to filter the container to include only images that are from 1 to 4 MB, set the size_min query parameter to 1048576 and the size_max query parameter to 4194304.

You can list VM images that have a status of active, queued, or saving.

You can use query parameters to sort the results of this operation.

  • sort_key. Sorts by an image attribute. Sorts in the natural sorting direction of the image attribute.

  • sort_dir. Sorts in a sort direction.

  • sort. Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, the default is desc.

To sort the response, use the sort_key and sort_dir query parameters:

GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc

Alternatively, specify the sort query parameter:

GET /v2/images?sort=name:asc,status:desc
Normal response codes
200
Request parameters
Parameter Style Type Description
limit (Optional) query xsd:int

Requests a page size of items. Returns a number of items up to a 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

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

Filters the response by a name, as a string.

A valid value is the name of an image.

visibility (Optional) query imageapi:string

Filters the response by an image visibility value or values.

Use the comma (,) character to separate multiple values. A valid value is public, private, or shared. If you omit this parameter, the response shows public, private, and shared images with a member status of accepted.

member_status (Optional) query imageapi:string

Filters the response by a member status.

A valid value is accepted, pending, rejected, or all. Default is accepted.

owner (Optional) query imageapi:string

Filters the response by a tenant ID.

Shows only images that are shared with this tenant owner.

status (Optional) query xsd:int

Filters the response by an image status.

A valid value is queued, saving, active, killed, deleted, or pending_delete.

size_min (Optional) query xsd:string

Filters the response by a minimum image size, in bytes.

size_max (Optional) query xsd:string

Filters the response by a maximum image size, in bytes.

sort_key (Optional) query xsd:string

Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.

sort_dir (Optional) query xsd:string

Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.

sort (Optional) query xsd:string

Sorts the response by one or more attribute and sort direction combinations. You can also set multiple sort keys and directions. Default direction is desc.

Use the comma (,) character to separate multiple values. For example:

GET /v2/images?sort=name:asc,status:desc
tag (Optional) query xsd:string

Filters the response by an image tag. For example, ?tag="cirros".

created_at (Optional) query xsd:dateTime

Filters the response by the date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

If you omit the created_at date and time stamp, its value is null.

updated_at (Optional) query xsd:string

Filters the response by the date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

If you omit the time zone, the UTC time zone is assumed.

If you omit the updated_at date and time stamp, its value is null.

Response parameters
Parameter Style Type Description
images plain xsd:list

A list of image objects.

status plain xsd:string

The image status.

name plain xsd:string

The name of the image.

Value might be null (JSON null data type).

tags plain xsd:list

A list of tag objects.

container_format plain xsd:string

The container format of the image.

The value might be null (JSON null data type).

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

kernel_id plain csapi:UUID

The UUID of the kernel.

disk_format plain xsd:string

The disk format of the image.

The value might be null (JSON null data type).

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

min_disk plain xsd:int

The minimum disk size in GB that is required to boot the image.

The value might be null (JSON null data type).

protected plain xsd:boolean

Image protection for deletion. A valid value is True or False. Default is False.

id plain csapi:UUID

The UUID of the image.

ramdisk_id plain csapi:UUID

The UUID of the ramdisk.

min_ram plain csapi:UUID

The minimum amount of RAM in MB that is required to boot the image.

The value might be null (JSON null data type).

checksum plain xsd:string

Hash that is used over the the image data. The Image service uses this value for verification.

The value might be null (JSON null data type).

owner plain xsd:string

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

The value might be null (JSON null data type).

visibility plain xsd:boolean

The image visibility. A valid value is public or private. Default is private.

virtual_size plain xsd:int

The virtual size of the image.

The value might be null (JSON null data type).

size plain xsd:int

The size of the image data, in bytes.

The value might be null (JSON null data type).

self plain xsd:string

The URL for the virtual machine image.

file plain xsd:string

The URL for the virtual machine image file.

schema plain xsd:string

The URL for schema of the virtual machine image.

schema plain xsd:string

The URL for schema of the virtual machine images.

first plain xsd:string

The 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",
            "virtual_size": null
        },
        {
            "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",
            "virtual_size": null
        }
    ],
    "schema": "/v2/schemas/images",
    "first": "/v2/images"
}
POST
/v2/images
Create image

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

 

The Location response header contains the URI for the image. The response body contains the new image entity.

Synchronous Postconditions

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

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

Name for the image. Note that the name of an image is not unique to an Image service node. The API cannot expect users to know the names of images that other users own.

id (Optional) plain csapi:UUID

A unique, user-defined image UUID, in the format:

nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn

Where n is a hexadecimal digit from 0 to f, or F.

For example:

b2173dd3-7ad6-4362-baa6-a68bce3565cb

If you omit this value, the API generates a UUID for the image.

visibility (Optional) plain xsd:string

Image visibility. Valid value is public or private. Default is public.

tags (Optional) plain xsd:list

Image tags.

container_format (Optional) plain xsd:string

Format of the container. A valid value is ami, ari, aki, bare, ovf, ova, or docker.

disk_format (Optional) plain xsd:string

The format of the disk. A valid value is ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, or iso.

min_disk (Optional) plain xsd:int

Amount of disk space in GB that is required to boot the image.

min_ram (Optional) plain xsd:int

Amount of RAM in MB that is required to boot the image.

protected (Optional) plain xsd:bool

Image protection for deletion. Valid value is true or false. Default is false.

properties (Optional) plain xsd:dict

The image properties, if any.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

container_format plain xsd:string

The container format of the image.

The value might be null (JSON null data type).

min_ram plain csapi:UUID

The minimum amount of RAM in MB that is required to boot the image.

The value might be null (JSON null data type).

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

owner plain xsd:string

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

The value might be null (JSON null data type).

min_disk plain xsd:int

The minimum disk size in GB that is required to boot the image.

The value might be null (JSON null data type).

tags plain xsd:list

A list of tag objects.

locations plain xsd:list

A list of URLs to access the image file in external store. This list appears if the show_multiple_locations option is set to True in the Image service's configuration file.

visibility plain xsd:boolean

The image visibility. A valid value is public or private. Default is private.

id plain csapi:UUID

The UUID of the image.

size plain xsd:int

The size of the image data, in bytes.

The value might be null (JSON null data type).

virtual_size plain xsd:int

The virtual size of the image.

The value might be null (JSON null data type).

name plain xsd:string

The name of the image.

Value might be null (JSON null data type).

checksum plain xsd:string

Hash that is used over the the image data. The Image service uses this value for verification.

The value might be null (JSON null data type).

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

disk_format plain xsd:string

The disk format of the image.

The value might be null (JSON null data type).

properties plain xsd:dict

The image properties, if any.

protected plain xsd:boolean

Image protection for deletion. A valid value is True or False. Default is False.

location header xsd:string

The URL to access the image file from the external store.

self plain xsd:string

The URL for the virtual machine image.

file plain xsd:string

The URL for the virtual machine image file.

schema plain xsd:string

The URL for schema of the virtual machine image.

{
    "container_format": "bare",
    "disk_format": "raw",
    "name": "Ubuntu",
    "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb"
}
{
    "status": "queued",
    "name": "Ubuntu",
    "tags": [],
    "container_format": "bare",
    "created_at": "2015-11-29T22:21:42Z",
    "size": null,
    "disk_format": "raw",
    "updated_at": "2015-11-29T22:21:42Z",
    "visibility": "private",
    "locations": [],
    "self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb",
    "min_disk": 0,
    "protected": false,
    "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb",
    "file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb/file",
    "checksum": null,
    "owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
    "virtual_size": null,
    "min_ram": 0,
    "schema": "/v2/schemas/image"
}
GET
/v2/images/​{image_id}​
Show image details

(Since Image API v2.0) Shows details for an image.

 

The response body contains a single image entity.

Preconditions

  • The image must exist.

Normal response codes
200
Error response codes
itemNotFound (404)
Request parameters
Parameter Style Type Description
image_id URI csapi:UUID

The UUID of the image.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

name plain xsd:string

The name of the image.

Value might be null (JSON null data type).

tags plain xsd:list

A list of tag objects.

container_format plain xsd:string

The container format of the image.

The value might be null (JSON null data type).

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

disk_format plain xsd:string

The disk format of the image.

The value might be null (JSON null data type).

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

min_disk plain xsd:int

The minimum disk size in GB that is required to boot the image.

The value might be null (JSON null data type).

protected plain xsd:boolean

Image protection for deletion. A valid value is True or False. Default is False.

id plain csapi:UUID

The UUID of the image.

min_ram plain csapi:UUID

The minimum amount of RAM in MB that is required to boot the image.

The value might be null (JSON null data type).

checksum plain xsd:string

Hash that is used over the the image data. The Image service uses this value for verification.

The value might be null (JSON null data type).

owner plain xsd:string

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

The value might be null (JSON null data type).

visibility plain xsd:boolean

The image visibility. A valid value is public or private. Default is private.

size plain xsd:int

The size of the image data, in bytes.

The value might be null (JSON null data type).

locations plain xsd:list

A list of URLs to access the image file in external store. This list appears if the show_multiple_locations option is set to True in the Image service's configuration file.

metadata plain xsd:dict

The location metadata.

properties plain xsd:dict

The image properties, if any.

direct_url plain xsd:string

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

self plain xsd:string

The URL for the virtual machine image.

file plain xsd:string

The URL for the virtual machine image file.

schema plain xsd:string

The 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",
    "virtual_size": null
}

This operation does not accept a request body.

PATCH
/v2/images/​{image_id}​
Update image

(Since Image API v2.0) Updates an image.

 

Depending on the referenced target location, this operation performs one of these actions:

Image update actions
Target location Update action

An array index

The API inserts a new value into the array at the index.

An object member that does not exist

The API adds a member to the object.

An object member that exists

The member value is replaced.

The operation object must contain a value member that contains the value to add. For example:

{
    "op": "add",
    "path": "/a/b/c",
    "value": [
        "foo",
        "bar"
    ]
}

The target location must reference one of these values:

  • The root of the target document. The value is the entire content of the target document.

  • A member value to add to an object. The API adds the value to the object at the location. If the member already exists, the API replaces it with the value.

  • An element to add to the array. The API adds the element value to the array at the location. The API shifts any element that is at or above the index one position to the right. The index must not be greater than the number of elements in the array. If you use the hyphen (-) character to index the end of the array, the API appends the value to the array. See JavaScript Object Notation (JSON) Pointer.

Because this operation adds to existing objects and arrays, its target location often does not exist.

The request body must conform to one of these 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 Image API v2 HTTP PATCH media types.

Preconditions

  • When you add a location to or replace a location in the image, you must set the disk_format and container_format parameters in the image.

  • When you replace a location, that location must be previously set in the image.

Synchronous Postconditions

  • With correct permissions, you can view the updated values of the attributes of the image.

  • After you add a location to an image that had no location and with correct permissions, you can use API calls to view the image status as active.

  • After you remove all locations from the image and with correct permissions, you can use API calls to view the image status as queued.

Troubleshooting

  • If you cannot update locations, your request might be missing some information. Make sure that you meet the preconditions and run the request again. If the request fails again, review your API request.

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

The UUID of the image.

path plain xsd:string

An image 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. A valid value is:

  • add. Adds a property or location in the image.

  • remove. Removes an image's property or location.

  • replace. Replaces the value of an image's property or location.

url plain xsd:string

The 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.

Value might be null (JSON null data type).

tags plain xsd:list

A list of tag objects.

container_format plain xsd:string

The container format of the image.

The value might be null (JSON null data type).

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

disk_format plain xsd:string

The disk format of the image.

The value might be null (JSON null data type).

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

min_disk plain xsd:int

The minimum disk size in GB that is required to boot the image.

The value might be null (JSON null data type).

protected plain xsd:boolean

Image protection for deletion. A valid value is True or False. Default is False.

id plain csapi:UUID

The UUID of the image.

min_ram plain csapi:UUID

The minimum amount of RAM in MB that is required to boot the image.

The value might be null (JSON null data type).

checksum plain xsd:string

Hash that is used over the the image data. The Image service uses this value for verification.

The value might be null (JSON null data type).

owner plain xsd:string

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

The value might be null (JSON null data type).

visibility plain xsd:boolean

The image visibility. A valid value is public or private. Default is private.

size plain xsd:int

The size of the image data, in bytes.

The value might be null (JSON null data type).

locations plain xsd:list

A list of URLs to access the image file in external store. This list appears if the show_multiple_locations option is set to True in the Image service's configuration file.

metadata plain xsd:dict

The location metadata.

properties plain xsd:dict

The image properties, if any.

direct_url plain xsd:string

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

self plain xsd:string

The URL for the virtual machine image.

file plain xsd:string

The URL for the virtual machine image file.

schema plain xsd:string

The 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",
    "owner": null,
    "min_ram": null,
    "min_disk": null,
    "disk_format": null,
    "virtual_size": null,
    "container_format": null
}
DELETE
/v2/images/​{image_id}​
Delete image

(Since Image API v2.0) Deletes an image.

 

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

Preconditions

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

  • First, set the protected attribute to false (boolean). Then, perform the delete.

Synchronous Postconditions

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

  • The API deletes the image from the images index.

  • If the image stores binary image data in the storage node, the OpenStack Image service deletes the data from the node.

Troubleshooting

  • The call returns the HTTP 403 response code when the protected attribute is set to true even if you have correct permissions. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.

Normal response codes
204
Error response codes
forbidden (403)
Request parameters
Parameter Style Type Description
image_id URI csapi:UUID

The UUID of the image.

This operation does not accept a request body and does not return a response body.

POST
/v2/images/​{image_id}​/actions/reactivate
Reactivate image

(Since Image API v2.0) Reactivates an image.

 

The reactivate operation returns an error if the image status is not active or deactivated.

Preconditions

  • The image must exist.

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

The UUID of the 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",
    "virtual_size": null
}

This operation does not accept a request body.

POST
/v2/images/​{image_id}​/actions/deactivate
Deactivate image

(Since Image API v2.0) Deactivates an image.

 

If you try to download a deactivated image, the call returns the Forbidden (403) response code. Also, only administrative users can view image locations for deactivated images.

The deactivate operation returns an error if the image status is not active or deactivated.

Preconditions

  • The image must exist.

Normal response codes
204
Error response codes
forbidden (403)
Request parameters
Parameter Style Type Description
image_id URI csapi:UUID

The UUID of the image.

{
    "status": "deactivated",
    "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",
    "virtual_size": null
}

This operation does not accept a request body.

Image data (images, file)

Uploads and downloads raw image data.

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

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

 

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

Before you can store binary image data, you must meet the following preconditions:

  • The image must exist.

  • You must set the disk and container formats in the image.

  • The image status must be queued.

  • Your image storage quota must be sufficient.

  • The size of the data that you want to store must not exceed the size that the OpenStack Image service allows.

Synchronous Postconditions

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

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

Troubleshooting

  • If you cannot store the data, either your request lacks required information or you exceeded your allotted quota. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.

  • The storage back ends for storing the data must have enough free storage space to accommodate the size of the data.

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

The UUID of the image.

This operation does not accept a request body and does not return a response body.

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

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

 

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 application/octet-stream value. The Content-MD5 header contains an MD5 checksum of the image data. Use this checksum to verify the integrity of the image data.

Preconditions

  • The images must exist.

Synchronous Postconditions

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

  • If image data exists, the call returns the HTTP 200 response code.

  • If no image data exists, the call returns the HTTP 204 response code.

Normal response codes
200, 204
Error response codes
forbidden (403)
Request parameters
Parameter Style Type Description
image_id URI csapi:UUID

The UUID of the image.

Content-Range (Optional) header xsd:string

The content range of image data. For details, see Hypertext Transfer Protocol (HTTP/1.1): Range Requests.

This operation does not return a response body.

Image tags (images, tags)

Adds and deletes image tags.

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

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

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

The UUID of the image.

tag URI xsd:string

The image tag.

This operation does not accept a request body and does not return a response body.

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

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

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

The UUID of the image.

tag URI xsd:string

The image tag.

This operation does not accept a request body and does not return a response body.

Members (images, members)

Creates, lists, updates, and deletes image members.

GET
/v2/images/​{image_id}​/members
List image members

(Since Image API v2.1) Lists the tenants that share this image.

 

If a user who shares this image makes this call, the member list contains only information for that user.

If a user who does not share this image makes this call, the call returns the HTTP 404 response code.

Preconditions

  • The image must exist.

  • You must be the owner or a member of the image.

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

The UUID of the image.

Response parameters
Parameter Style Type Description
members plain xsd:list

A list of member objects. Each member object describes a member with whom this image is being shared.

status plain xsd:string

The image status.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

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"
}

This operation does not accept a request body.

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

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

 

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

Preconditions

  • The images must exist.

  • You can add a member to a private image.

  • You must be the owner of the 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 response code. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.

  • If the member is already a member for the image, the service returns the Conflict (409) response code. If you meant to specify a different member, run the request again.

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

The UUID of the image.

member_id (Optional) plain xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

member (Optional) plain xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

Response parameters
Parameter Style Type Description
created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

image_id URI csapi:UUID

The UUID of the image.

member_id plain xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

schema plain xsd:string

The URL for schema of the member.

status plain xsd:string

The image status.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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/​{member_id}​
Show image member details

(Since Image API v2.2) Shows image member details.

 

Response body is a single image member entity.

Preconditions

  • The image must exist.

  • You must be the owner or a member of the image.

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

The UUID of the image.

member_id URI xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

Response parameters
Parameter Style Type Description
status plain xsd:string

The image status.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

image_id plain csapi:UUID

The UUID of the image.

member_id plain xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

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"
}

This operation does not accept a request body.

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

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

 

Preconditions

  • The images must exist.

  • You must be a member of the image.

Synchronous Postconditions

  • If you update the member status to accepted and have the correct permissions, you see the image in list images responses.

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

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

The UUID of the image.

member_id URI xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

status plain xsd:string

The status of this image member.

Response parameters
Parameter Style Type Description
created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

image_id URI csapi:UUID

The UUID of the image.

member_id plain xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This call accepts either the member_id or member attribute in the request body. If you specify both attributes, the API uses the member_id value and ignores the member value. Use of the member attribute is supported but deprecated. Use of the member_id attribute is preferred.

schema plain xsd:string

The URL for schema of the member.

status plain xsd:string

The image status.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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"
}
DELETE
/v2/images/​{image_id}​/members/​{member_id}​
Delete image member

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

 

Preconditions

  • The image must exist.

  • You must be the owner of the image.

Synchronous Postconditions

  • The API removes the member from the image members.

Troubleshooting

  • Even if you have correct permissions, if you are not the owner of the image or you specify an incorrect image ID or member ID, the call returns the HTTP 403 or 404 response code. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request URI.

Normal response codes
204
Error response codes
forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
image_id URI csapi:UUID

The UUID of the image.

member_id URI xsd:string

The ID of the image member. An image member is a tenant with whom the image is shared.

This operation does not accept a request body and does not return a response body.

Image schemas (schemas, image, images, member, members)

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

GET
/v2/schemas/images
Show images schema

(Since Images v2.0) Shows a JSON schema document that represents an images entity.

 

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
{
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "images",
    "properties": {
        "first": {
            "type": "string"
        },
        "images": {
            "items": {
                "additionalProperties": {
                    "type": "string"
                },
                "links": [
                    {
                        "href": "{self}",
                        "rel": "self"
                    },
                    {
                        "href": "{file}",
                        "rel": "enclosure"
                    },
                    {
                        "href": "{schema}",
                        "rel": "describedby"
                    }
                ],
                "name": "image",
                "properties": {
                    "architecture": {
                        "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
                        "is_base": false,
                        "type": "string"
                    },
                    "checksum": {
                        "description": "md5 hash of image contents. (READ-ONLY)",
                        "maxLength": 32,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "container_format": {
                        "description": "Format of the container",
                        "enum": [
                            null,
                            "ami",
                            "ari",
                            "aki",
                            "bare",
                            "ovf",
                            "ova"
                        ],
                        "type": [
                            "null",
                            "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": [
                            null,
                            "ami",
                            "ari",
                            "aki",
                            "vhd",
                            "vmdk",
                            "raw",
                            "qcow2",
                            "vdi",
                            "iso"
                        ],
                        "type": [
                            "null",
                            "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.",
                        "is_base": false,
                        "type": "string"
                    },
                    "kernel_id": {
                        "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
                        "is_base": false,
                        "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": [
                            "null",
                            "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",
                        "is_base": false,
                        "type": "string"
                    },
                    "os_version": {
                        "description": "Operating system version as specified by the distributor",
                        "is_base": false,
                        "type": "string"
                    },
                    "owner": {
                        "description": "Owner of the image",
                        "maxLength": 255,
                        "type": [
                            "null",
                            "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.",
                        "is_base": false,
                        "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": [
                            "null",
                            "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": [
                            "null",
                            "integer"
                        ]
                    },
                    "visibility": {
                        "description": "Scope of image accessibility",
                        "enum": [
                            "public",
                            "private"
                        ],
                        "type": "string"
                    }
                }
            },
            "type": "array"
        },
        "next": {
            "type": "string"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/image
Show image schema

(Since Images v2.0) Shows a JSON schema document that represents an image entity.

 

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

Normal response codes
200
{
    "additionalProperties": {
        "type": "string"
    },
    "links": [
        {
            "href": "{self}",
            "rel": "self"
        },
        {
            "href": "{file}",
            "rel": "enclosure"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "image",
    "properties": {
        "architecture": {
            "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
            "is_base": false,
            "type": "string"
        },
        "checksum": {
            "description": "md5 hash of image contents. (READ-ONLY)",
            "maxLength": 32,
            "type": [
                "null",
                "string"
            ]
        },
        "container_format": {
            "description": "Format of the container",
            "enum": [
                null,
                "ami",
                "ari",
                "aki",
                "bare",
                "ovf",
                "ova"
            ],
            "type": [
                "null",
                "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": [
                null,
                "ami",
                "ari",
                "aki",
                "vhd",
                "vmdk",
                "raw",
                "qcow2",
                "vdi",
                "iso"
            ],
            "type": [
                "null",
                "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.",
            "is_base": false,
            "type": "string"
        },
        "kernel_id": {
            "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
            "is_base": false,
            "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": [
                "null",
                "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",
            "is_base": false,
            "type": "string"
        },
        "os_version": {
            "description": "Operating system version as specified by the distributor",
            "is_base": false,
            "type": "string"
        },
        "owner": {
            "description": "Owner of the image",
            "maxLength": 255,
            "type": [
                "null",
                "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.",
            "is_base": false,
            "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": [
                "null",
                "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": [
                "null",
                "integer"
            ]
        },
        "visibility": {
            "description": "Scope of image accessibility",
            "enum": [
                "public",
                "private"
            ],
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/members
Show image members schema

(Since Images v2.1) Shows a JSON schema document that represents an image members entity.

 

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
{
    "links": [
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "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"
                    },
                    "schema": {
                        "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"
                    }
                }
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/member
Show image member schema

(Since Images v2.1) Shows a JSON schema document that represents an image member entity.

 

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"
        },
        "schema": {
            "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"
        }
    }
}

This operation does not accept a request body.

Metadata definition resource types (since API v2.0) (metadefs, namespaces, resource_types)

Lists resource types. Also, creates, lists, and removes resource type associations in a namespace.

GET
/v2/metadefs/resource_types
List resource types

Lists all resource types.

 

You can assign metadata definition namespaces to these resource types. See the metadata definition resource types section.

Normal response codes
200
{
    "resource_types": [
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Glance::Image",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Cinder::Volume",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Flavor",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Aggregate",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Instance",
            "updated_at": "2014-08-28T18:13:04Z"
        }
    ]
}

This operation does not accept a request body.

POST
/v2/metadefs/namespaces/​{namespace_id}​/resource_types
Create resource type association

Creates a resource type association in a namespace.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

name plain xsd:string

Name of the resource type.

prefix (Optional) plain xsd:string

Prefix for any properties in the namespace that you want to apply to the resource type. If you specify a prefix, you must append a prefix separator, such as the colon (:) character.

properties_target (Optional) plain xsd:string

Some resource types allow more than one key and value pair for each instance. For example, the Image service allows both user and image metadata on volumes. The properties_target parameter enables a namespace target to remove the ambiguity.

{
    "name": "OS::Cinder::Volume",
    "prefix": "hw_",
    "properties_target": "image"
}
{
    "created_at": "2014-09-19T16:09:13Z",
    "name": "OS::Cinder::Volume",
    "prefix": "hw_",
    "properties_target": "image",
    "updated_at": "2014-09-19T16:09:13Z"
}
GET
/v2/metadefs/namespaces/​{namespace_id}​/resource_types
List resource type associations

Lists resource type associations in a namespace.

 

The response body lists resource type association entities.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

{
    "resource_types": [
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Glance::Image",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Cinder::Volume",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Flavor",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Aggregate",
            "updated_at": "2014-08-28T18:13:04Z"
        },
        {
            "created_at": "2014-08-28T18:13:04Z",
            "name": "OS::Nova::Instance",
            "updated_at": "2014-08-28T18:13:04Z"
        }
    ]
}

This operation does not accept a request body.

DELETE
/v2/metadefs/namespaces/​{namespace_id}​/resource_types/​{name}​
Remove resource type association

Removes a resource type association in a namespace.

 

To remove an association, first make an update namespace request to set the protected attribute to false (boolean) on the namespace. Then, remove the association. If the operation succeeds, the response returns the HTTP 204 status code.

If you try to remove resource type associations in a namespace with the protected attribute set to true (boolean), the operation fails and the response returns the HTTP 403 error code.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

name URI xsd:string

Name of the resource type.

This operation does not accept a request body and does not return a response body.

Metadata definition namespaces (since API v2.0) (metadefs, namespaces)

Creates, lists, shows details for, updates, and deletes metadata definition namespaces. Defines namespaces that can contain property definitions, object definitions, and resource type associations.

POST
/v2/metadefs/namespaces
Create namespace

Creates a namespace.

 

The Location response header contains the newly-created URI for the namespace.

Normal response codes
201
Response parameters
Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User-friendly name to use in a UI to display the namespace name.

description plain xsd:string

The description of the namespace.

visibility plain xsd:string

The namespace visibility. A valid value is public or private. Default is private.

protected plain xsd:string

Namespace protection for deletion. A valid value is True or False. Default is False.

properties plain xsd:string

One or more property definitions for the namespace.

objects plain xsd:string

One or more object definitions of the namespace.

resource_type_associations plain xsd:string

One or more namespace resource types.

{
    "description": "Choose capabilities that should be provided by the Compute Host. This provides the ability to fine tune the hardware specification required when a new vm is requested.",
    "display_name": "Hypervisor Selection",
    "namespace": "OS::Compute::Hypervisor",
    "properties": {
        "hypervisor_type": {
            "description": "The hypervisor type.",
            "enum": [
                "xen",
                "qemu",
                "kvm",
                "lxc",
                "uml",
                "vmware",
                "hyperv"
            ],
            "title": "Hypervisor Type",
            "type": "string"
        },
        "vm_mode": {
            "description": "The virtual machine mode.",
            "enum": [
                "hvm",
                "xen",
                "uml",
                "exe"
            ],
            "title": "VM Mode",
            "type": "string"
        }
    },
    "protected": true,
    "resource_type_associations": [
        {
            "name": "OS::Glance::Image"
        }
    ],
    "visibility": "public"
}
{
    "description": "Choose capabilities that should be provided by the Compute Host. This provides the ability to fine tune the hardware specification required when a new vm is requested.",
    "display_name": "Hypervisor Selection",
    "namespace": "OS::Compute::Hypervisor",
    "properties": {
        "hypervisor_type": {
            "description": "The hypervisor type.",
            "enum": [
                "xen",
                "qemu",
                "kvm",
                "lxc",
                "uml",
                "vmware",
                "hyperv"
            ],
            "title": "Hypervisor Type",
            "type": "string"
        },
        "vm_mode": {
            "description": "The virtual machine mode.",
            "enum": [
                "hvm",
                "xen",
                "uml",
                "exe"
            ],
            "title": "VM Mode",
            "type": "string"
        }
    },
    "protected": true,
    "resource_type_associations": [
        {
            "name": "OS::Glance::Image"
        }
    ],
    "schema": "/v2/schemas/metadefs/namespace",
    "self": "/v2/metadefs/namespaces/OS::Compute::Hypervisor",
    "visibility": "public"
}
GET
/v2/metadefs/namespaces
List namespaces

Lists public namespaces.

 

Returns a subset in the larger collection of namespaces and a link that you can use to get the next set of namespaces. Check for the presence of a next link and use it as the URI in a subsequent HTTP 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 return to the first page in the collection. If you prefer to paginate through namespaces manually, use the limit and marker parameters.

The list operation accepts the resource_types and visibility query parameters, which you can use to filter the response.

To sort the results of this operation, use the sort_key and sort_dir parameters. The API uses the natural sorting order in the namespace attribute that you provide as the sort_key parameter.

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

Requests a page size of items. Returns a number of items up to a 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

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.

visibility (Optional) query imageapi:string

Filters the response by an image visibility value or values.

Use the comma (,) character to separate multiple values. A valid value is public, private, or shared. If you omit this parameter, the response shows public, private, and shared images with a member status of accepted.

resource_types (Optional) query xsd:int

Filters the response by a resource type or types.

Use the comma (,) character to separate multiple values. For example, OS::Glance::Image,OS::Nova::Flavor shows only namespaces for these resource types.

sort_key (Optional) query xsd:string

Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.

sort_dir (Optional) query xsd:string

Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.

Response parameters
Parameter Style Type Description
namespaces plain xsd:list

A list of namespace objects.

namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User-friendly name to use in a UI to display the namespace name.

description plain xsd:string

The description of the namespace.

visibility plain xsd:string

The namespace visibility. A valid value is public or private. Default is private.

protected plain xsd:string

Namespace protection for deletion. A valid value is True or False. Default is False.

resource_type_associations plain xsd:string

One or more namespace resource types.

{
    "first": "/v2/metadefs/namespaces?sort_key=created_at&sort_dir=asc",
    "namespaces": [
        {
            "created_at": "2014-08-28T17:13:06Z",
            "description": "The libvirt compute driver options. These are properties specific to compute drivers.  For a list of all hypervisors, see here: https://wiki.openstack.org/wiki/HypervisorSupportMatrix.",
            "display_name": "libvirt Driver Options",
            "namespace": "OS::Compute::Libvirt",
            "owner": "admin",
            "protected": true,
            "resource_type_associations": [
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Glance::Image",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "schema": "/v2/schemas/metadefs/namespace",
            "self": "/v2/metadefs/namespaces/OS::Compute::Libvirt",
            "updated_at": "2014-08-28T17:13:06Z",
            "visibility": "public"
        },
        {
            "created_at": "2014-08-28T17:13:06Z",
            "description": "Compute drivers may enable quotas on CPUs available to a VM, disk tuning, bandwidth I/O, and instance VIF traffic control.  See: http://docs.openstack.org/admin-guide-cloud/compute-flavors.html",
            "display_name": "Flavor Quota",
            "namespace": "OS::Compute::Quota",
            "owner": "admin",
            "protected": true,
            "resource_type_associations": [
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Nova::Flavor",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "schema": "/v2/schemas/metadefs/namespace",
            "self": "/v2/metadefs/namespaces/OS::Compute::Quota",
            "updated_at": "2014-08-28T17:13:06Z",
            "visibility": "public"
        },
        {
            "created_at": "2014-08-28T17:13:06Z",
            "description": "Trusted compute pools with Intel\u00ae Trusted Execution Technology (Intel\u00ae TXT) support IT compliance by protecting virtualized data centers - private, public, and hybrid clouds against attacks toward hypervisor and BIOS, firmware, and other pre-launch software components.",
            "display_name": "Trusted Compute Pools (Intel\u00ae TXT)",
            "namespace": "OS::Compute::Trust",
            "owner": "admin",
            "protected": true,
            "resource_type_associations": [
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Nova::Flavor",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "schema": "/v2/schemas/metadefs/namespace",
            "self": "/v2/metadefs/namespaces/OS::Compute::Trust",
            "updated_at": "2014-08-28T17:13:06Z",
            "visibility": "public"
        },
        {
            "created_at": "2014-08-28T17:13:06Z",
            "description": "This provides the preferred socket/core/thread counts for the virtual CPU instance exposed to guests. This enables the ability to avoid hitting limitations on vCPU topologies that OS vendors place on their products. See also: http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/juno/virt-driver-vcpu-topology.rst",
            "display_name": "Virtual CPU Topology",
            "namespace": "OS::Compute::VirtCPUTopology",
            "owner": "admin",
            "protected": true,
            "resource_type_associations": [
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Glance::Image",
                    "prefix": "hw_",
                    "updated_at": "2014-08-28T17:13:06Z"
                },
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Cinder::Volume",
                    "prefix": "hw_",
                    "properties_target": "image",
                    "updated_at": "2014-08-28T17:13:06Z"
                },
                {
                    "created_at": "2014-08-28T17:13:06Z",
                    "name": "OS::Nova::Flavor",
                    "prefix": "hw:",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "schema": "/v2/schemas/metadefs/namespace",
            "self": "/v2/metadefs/namespaces/OS::Compute::VirtCPUTopology",
            "updated_at": "2014-08-28T17:13:06Z",
            "visibility": "public"
        }
    ],
    "schema": "/v2/schemas/metadefs/namespaces"
}
GET
/v2/metadefs/namespaces/​{namespace_id}​
Get namespaces details

Gets details for a namespace.

 

The response body shows a single namespace entity with all details including properties and objects.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

{
    "created_at": "2014-08-28T17:13:06Z",
    "description": "The libvirt compute driver options. These are properties specific to compute drivers.  For a list of all hypervisors, see here: https://wiki.openstack.org/wiki/HypervisorSupportMatrix.",
    "display_name": "libvirt Driver Options",
    "namespace": "OS::Compute::Libvirt",
    "owner": "admin",
    "properties": {
        "hw_disk_bus": {
            "description": "Specifies the type of disk controller to attach disk devices to.",
            "enum": [
                "scsi",
                "virtio",
                "uml",
                "xen",
                "ide",
                "usb"
            ],
            "title": "Disk Bus",
            "type": "string"
        },
        "hw_machine_type": {
            "description": "Enables booting an ARM system using the specified machine type. By default, if an ARM image is used and its type is not specified, Compute uses vexpress-a15 (for ARMv7) or virt (for AArch64) machine types. Valid types can be viewed by using the virsh capabilities command (machine types are displayed in the machine tag).",
            "title": "Machine Type",
            "type": "string"
        },
        "hw_qemu_guest_agent": {
            "description": "It is a daemon program running inside the domain which is supposed to help management applications with executing functions which need assistance of the guest OS. For example, freezing and thawing filesystems, entering suspend. However, guest agent (GA) is not bullet proof, and hostile guest OS can send spurious replies.",
            "enum": [
                "yes",
                "no"
            ],
            "title": "QEMU Guest Agent",
            "type": "string"
        },
        "hw_rng_model": {
            "default": "virtio",
            "description": "Adds a random-number generator device to the image's instances. The cloud administrator can enable and control device behavior by configuring the instance's flavor. By default: The generator device is disabled. /dev/random is used as the default entropy source. To specify a physical HW RNG device, use the following option in the nova.conf file: rng_dev_path=/dev/hwrng",
            "title": "Random Number Generator Device",
            "type": "string"
        },
        "hw_scsi_model": {
            "default": "virtio-scsi",
            "description": "Enables the use of VirtIO SCSI (virtio-scsi) to provide block device access for compute instances; by default, instances use VirtIO Block (virtio-blk). VirtIO SCSI is a para-virtualized SCSI controller device that provides improved scalability and performance, and supports advanced SCSI hardware.",
            "title": "SCSI Model",
            "type": "string"
        },
        "hw_video_model": {
            "description": "The video image driver used.",
            "enum": [
                "vga",
                "cirrus",
                "vmvga",
                "xen",
                "qxl"
            ],
            "title": "Video Model",
            "type": "string"
        },
        "hw_video_ram": {
            "description": "Maximum RAM for the video image. Used only if a hw_video:ram_max_mb value has been set in the flavor's extra_specs and that value is higher than the value set in hw_video_ram.",
            "title": "Max Video Ram",
            "type": "integer"
        },
        "hw_vif_model": {
            "description": "Specifies the model of virtual network interface device to use. The valid options depend on the configured hypervisor. KVM and QEMU: e1000, ne2k_pci, pcnet, rtl8139, and virtio. VMware: e1000, e1000e, VirtualE1000, VirtualE1000e, VirtualPCNet32, VirtualSriovEthernetCard, and VirtualVmxnet. Xen: e1000, netfront, ne2k_pci, pcnet, and rtl8139.",
            "enum": [
                "e1000",
                "ne2k_pci",
                "pcnet",
                "rtl8139",
                "virtio",
                "e1000",
                "e1000e",
                "VirtualE1000",
                "VirtualE1000e",
                "VirtualPCNet32",
                "VirtualSriovEthernetCard",
                "VirtualVmxnet",
                "netfront",
                "ne2k_pci"
            ],
            "title": "Virtual Network Interface",
            "type": "string"
        },
        "os_command_line": {
            "description": "The kernel command line to be used by the libvirt driver, instead of the default. For linux containers (LXC), the value is used as arguments for initialization. This key is valid only for Amazon kernel, ramdisk, or machine images (aki, ari, or ami).",
            "title": "Kernel Command Line",
            "type": "string"
        }
    },
    "protected": true,
    "resource_type_associations": [
        {
            "created_at": "2014-08-28T17:13:06Z",
            "name": "OS::Glance::Image",
            "updated_at": "2014-08-28T17:13:06Z"
        }
    ],
    "schema": "/v2/schemas/metadefs/namespace",
    "self": "/v2/metadefs/namespaces/OS::Compute::Libvirt",
    "updated_at": "2014-08-28T17:13:06Z",
    "visibility": "public"
}

This operation does not accept a request body.

PUT
/v2/metadefs/namespaces/​{namespace_id}​
Update namespace

Updates a namespace.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

{
    "description": "Choose capabilities that should be provided by the Compute Host. This provides the ability to fine tune the hardware specification required when a new vm is requested.",
    "display_name": "Hypervisor Selection",
    "namespace": "OS::Compute::Hypervisor",
    "protected": false,
    "visibility": "public"
}
{
    "created_at": "2014-09-19T13:31:37Z",
    "description": "Choose capabilities that should be provided by the Compute Host. This provides the ability to fine tune the harware specification required when a new vm is requested.",
    "display_name": "Hypervisor Selection",
    "namespace": "OS::Compute::Hypervisor",
    "owner": "7ec22942411e427692e8a3436be1031a",
    "protected": false,
    "schema": "/v2/schemas/metadefs/namespace",
    "self": "/v2/metadefs/namespaces/OS::Compute::Hypervisor",
    "updated_at": "2014-09-19T13:31:37Z",
    "visibility": "public"
}
DELETE
/v2/metadefs/namespaces/​{namespace_id}​
Delete namespace

Deletes a namespace and its properties, objects, and any resource type associations.

 

You cannot delete namespaces with the protected attribute set to true (boolean); the response returns the HTTP 403 response code.

To delete a namespace, you must first make an update namespace request to set the protected attribute to false (boolean) on the namespace. Then, delete the namespace.

A successful operation returns the HTTP 204 response code.

If you try to remove a namespace with the protected attribute set to true (boolean), the operation fails and the response returns the HTTP 403 response code.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

This operation does not accept a request body and does not return a response body.

Metadata definition properties (since API v2.0) (metadefs, namespaces, properties)

Creates, lists, shows details for, updates, and deletes metadata definition properties.

POST
/v2/metadefs/namespaces/​{namespace_id}​/properties
Create property

Creates a property definition in a namespace.

 

The schema is a subset of the JSON property definition schema.

Normal response codes
201
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum (Optional) plain xsd:list

Enumerated list of property values.

items (Optional) plain xsd:string

Schema for the items in an array.

description (Optional) plain xsd:string

The description of the property.

operators (Optional) plain xsd:string

Operators property description.

default (Optional) plain xsd:base64Binary

Default property description.

readonly (Optional) plain xsd:boolean

Indicates whether this is a read-only property.

minimum (Optional) plain xsd:string

Minimum allowed numerical value.

maximum (Optional) plain xsd:string

Maximum allowed numerical value.

minLength (Optional) plain xsd:string

Minimum allowed string length.

maxLength (Optional) plain xsd:string

Maximum allowed string length.

pattern (Optional) plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems (Optional) plain xsd:string

Minimum length of an array.

maxItems (Optional) plain xsd:string

Maximum length of an array.

uniqueItems (Optional) plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems (Optional) plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum plain xsd:list

An enumerated list of property values.

items plain xsd:string

Schema for the items in an array.

description plain xsd:string

The description of the property.

operators plain xsd:string

Operators property description.

default plain xsd:base64Binary

Default property description.

readonly plain xsd:boolean

Indicates whether this is a read-only property.

minimum plain xsd:string

Minimum allowed numerical value.

maximum plain xsd:string

Maximum allowed numerical value.

minLength plain xsd:string

Minimum allowed string length.

maxLength plain xsd:string

Maximum allowed string length.

pattern plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems plain xsd:string

Minimum length of an array.

maxItems plain xsd:string

Maximum length of an array.

uniqueItems plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

{
    "description": "The hypervisor type. It may be used by the host properties filter for scheduling. The ImagePropertiesFilter filters compute nodes that satisfy any architecture, hypervisor type, or virtual machine mode properties specified on the instance's image properties. Image properties are contained in the image dictionary in the request_spec.",
    "enum": [
        "xen",
        "qemu",
        "kvm",
        "lxc",
        "uml",
        "vmware",
        "hyperv"
    ],
    "name": "hypervisor_type",
    "title": "Hypervisor Type",
    "type": "string"
}
{
    "description": "The hypervisor type. It may be used by the host properties filter for scheduling. The ImagePropertiesFilter filters compute nodes that satisfy any architecture, hypervisor type, or virtual machine mode properties specified on the instance's image properties. Image properties are contained in the image dictionary in the request_spec.",
    "enum": [
        "xen",
        "qemu",
        "kvm",
        "lxc",
        "uml",
        "vmware",
        "hyperv"
    ],
    "name": "hypervisor_type",
    "title": "Hypervisor Type",
    "type": "string"
}
GET
/v2/metadefs/namespaces/​{namespace_id}​/properties
List property definitions

Lists property definitions in a namespace.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

Response parameters
Parameter Style Type Description
properties plain xsd:list

A list of property objects.

name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum plain xsd:list

An enumerated list of property values.

items plain xsd:string

Schema for the items in an array.

description plain xsd:string

The description of the property.

operators plain xsd:string

Operators property description.

default plain xsd:base64Binary

Default property description.

readonly plain xsd:boolean

Indicates whether this is a read-only property.

minimum plain xsd:string

Minimum allowed numerical value.

maximum plain xsd:string

Maximum allowed numerical value.

minLength plain xsd:string

Minimum allowed string length.

maxLength plain xsd:string

Maximum allowed string length.

pattern plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems plain xsd:string

Minimum length of an array.

maxItems plain xsd:string

Maximum length of an array.

uniqueItems plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

{
    "properties": {
        "hw_disk_bus": {
            "description": "Specifies the type of disk controller to attach disk devices to.",
            "enum": [
                "scsi",
                "virtio",
                "uml",
                "xen",
                "ide",
                "usb"
            ],
            "title": "Disk Bus",
            "type": "string"
        },
        "hw_machine_type": {
            "description": "Enables booting an ARM system using the specified machine type. By default, if an ARM image is used and its type is not specified, Compute uses vexpress-a15 (for ARMv7) or virt (for AArch64) machine types. Valid types can be viewed by using the virsh capabilities command (machine types are displayed in the machine tag).",
            "title": "Machine Type",
            "type": "string"
        },
        "hw_qemu_guest_agent": {
            "description": "It is a daemon program running inside the domain which is supposed to help management applications with executing functions which need assistance of the guest OS. For example, freezing and thawing filesystems, entering suspend. However, guest agent (GA) is not bullet proof, and hostile guest OS can send spurious replies.",
            "enum": [
                "yes",
                "no"
            ],
            "title": "QEMU Guest Agent",
            "type": "string"
        },
        "hw_rng_model": {
            "default": "virtio",
            "description": "Adds a random-number generator device to the image's instances. The cloud administrator can enable and control device behavior by configuring the instance's flavor. By default: The generator device is disabled. /dev/random is used as the default entropy source. To specify a physical HW RNG device, use the following option in the nova.conf file: rng_dev_path=/dev/hwrng",
            "title": "Random Number Generator Device",
            "type": "string"
        },
        "hw_scsi_model": {
            "default": "virtio-scsi",
            "description": "Enables the use of VirtIO SCSI (virtio-scsi) to provide block device access for compute instances; by default, instances use VirtIO Block (virtio-blk). VirtIO SCSI is a para-virtualized SCSI controller device that provides improved scalability and performance, and supports advanced SCSI hardware.",
            "title": "SCSI Model",
            "type": "string"
        },
        "hw_video_model": {
            "description": "The video image driver used.",
            "enum": [
                "vga",
                "cirrus",
                "vmvga",
                "xen",
                "qxl"
            ],
            "title": "Video Model",
            "type": "string"
        },
        "hw_video_ram": {
            "description": "Maximum RAM for the video image. Used only if a hw_video:ram_max_mb value has been set in the flavor's extra_specs and that value is higher than the value set in hw_video_ram.",
            "title": "Max Video Ram",
            "type": "integer"
        },
        "hw_vif_model": {
            "description": "Specifies the model of virtual network interface device to use. The valid options depend on the configured hypervisor. KVM and QEMU: e1000, ne2k_pci, pcnet, rtl8139, and virtio. VMware: e1000, e1000e, VirtualE1000, VirtualE1000e, VirtualPCNet32, VirtualSriovEthernetCard, and VirtualVmxnet. Xen: e1000, netfront, ne2k_pci, pcnet, and rtl8139.",
            "enum": [
                "e1000",
                "ne2k_pci",
                "pcnet",
                "rtl8139",
                "virtio",
                "e1000",
                "e1000e",
                "VirtualE1000",
                "VirtualE1000e",
                "VirtualPCNet32",
                "VirtualSriovEthernetCard",
                "VirtualVmxnet",
                "netfront",
                "ne2k_pci"
            ],
            "title": "Virtual Network Interface",
            "type": "string"
        },
        "os_command_line": {
            "description": "The kernel command line to be used by the libvirt driver, instead of the default. For linux containers (LXC), the value is used as arguments for initialization. This key is valid only for Amazon kernel, ramdisk, or machine images (aki, ari, or ami).",
            "title": "Kernel Command Line",
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/metadefs/namespaces/​{namespace_id}​/properties/​{property_name}​
Show property definition

Shows the definition for a property.

 

If you use the resource_type query parameter, the API removes the prefix of the resource type from the property name before it submits the query. This enables you to look for a property name that starts with a prefix from an associated resource type.

The response body shows a single property entity.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

property_name URI xsd:string

The name of the property.

property_name plain xsd:string

The name of the property.

resource_type (Optional) query xsd:int

Filters the response by property names that start with a prefix from an associated resource type.

The API removes the prefix of the resource type from the property name in the response.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum plain xsd:list

An enumerated list of property values.

items plain xsd:string

Schema for the items in an array.

description plain xsd:string

The description of the property.

operators plain xsd:string

Operators property description.

default plain xsd:base64Binary

Default property description.

readonly plain xsd:boolean

Indicates whether this is a read-only property.

minimum plain xsd:string

Minimum allowed numerical value.

maximum plain xsd:string

Maximum allowed numerical value.

minLength plain xsd:string

Minimum allowed string length.

maxLength plain xsd:string

Maximum allowed string length.

pattern plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems plain xsd:string

Minimum length of an array.

maxItems plain xsd:string

Maximum length of an array.

uniqueItems plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

{
    "description": "The hypervisor type. It may be used by the host properties filter for scheduling. The ImagePropertiesFilter filters compute nodes that satisfy any architecture, hypervisor type, or virtual machine mode properties specified on the instance's image properties. Image properties are contained in the image dictionary in the request_spec.",
    "enum": [
        "xen",
        "qemu",
        "kvm",
        "lxc",
        "uml",
        "vmware",
        "hyperv"
    ],
    "name": "hypervisor_type",
    "title": "Hypervisor Type",
    "type": "string"
}
PUT
/v2/metadefs/namespaces/​{namespace_id}​/properties/​{property_name}​
Update property definition

Updates a property definition.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

property_name URI xsd:string

The name of the property.

property_name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum (Optional) plain xsd:list

Enumerated list of property values.

items (Optional) plain xsd:string

Schema for the items in an array.

description (Optional) plain xsd:string

The description of the property.

operators (Optional) plain xsd:string

Operators property description.

default (Optional) plain xsd:base64Binary

Default property description.

readonly (Optional) plain xsd:boolean

Indicates whether this is a read-only property.

minimum (Optional) plain xsd:string

Minimum allowed numerical value.

maximum (Optional) plain xsd:string

Maximum allowed numerical value.

minLength (Optional) plain xsd:string

Minimum allowed string length.

maxLength (Optional) plain xsd:string

Maximum allowed string length.

pattern (Optional) plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems (Optional) plain xsd:string

Minimum length of an array.

maxItems (Optional) plain xsd:string

Maximum length of an array.

uniqueItems (Optional) plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems (Optional) plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the property.

title plain xsd:string

The title of the property.

type plain xsd:string

The property type.

enum plain xsd:list

An enumerated list of property values.

items plain xsd:string

Schema for the items in an array.

description plain xsd:string

The description of the property.

operators plain xsd:string

Operators property description.

default plain xsd:base64Binary

Default property description.

readonly plain xsd:boolean

Indicates whether this is a read-only property.

minimum plain xsd:string

Minimum allowed numerical value.

maximum plain xsd:string

Maximum allowed numerical value.

minLength plain xsd:string

Minimum allowed string length.

maxLength plain xsd:string

Maximum allowed string length.

pattern plain xsd:string

A regular expression (ECMA 262) that a string value must match.

minItems plain xsd:string

Minimum length of an array.

maxItems plain xsd:string

Maximum length of an array.

uniqueItems plain xsd:string

Indicates whether all values in the array must be distinct.

additionalItems plain xsd:string

Describes extra items, if you use tuple typing. If the value of items is an array (tuple typing) and the instance is longer than the list of schemas in items, the additional items are described by the schema in this property.

If this value is false, the instance cannot be longer than the list of schemas in items.

If this value is true, that is equivalent to the empty schema (anything goes).

{
    "description": "The hypervisor type. It may be used by the host properties filter for scheduling. The ImagePropertiesFilter filters compute nodes that satisfy any architecture, hypervisor type, or virtual machine mode properties specified on the instance's image properties. Image properties are contained in the image dictionary in the request_spec.",
    "enum": [
        "xen",
        "qemu",
        "kvm",
        "lxc",
        "uml",
        "vmware",
        "hyperv"
    ],
    "name": "hypervisor_type",
    "title": "Hypervisor Type",
    "type": "string"
}
{
    "description": "The hypervisor type. It may be used by the host properties filter for scheduling. The ImagePropertiesFilter filters compute nodes that satisfy any architecture, hypervisor type, or virtual machine mode properties specified on the instance's image properties. Image properties are contained in the image dictionary in the request_spec.",
    "enum": [
        "xen",
        "qemu",
        "kvm",
        "lxc",
        "uml",
        "vmware",
        "hyperv"
    ],
    "name": "hypervisor_type",
    "title": "Hypervisor Type",
    "type": "string"
}
DELETE
/v2/metadefs/namespaces/​{namespace_id}​/properties/​{property_name}​
Remove property definition

Removes a property definition in a namespace.

 

To remove a property, first make an update namespace request to set the protected attribute to false (boolean) on the namespace. Then, remove the property. If the operation succeeds, the response returns the HTTP 204 status code.

If you try to remove a property in a namespace with the protected attribute set to true (boolean), the operation fails and the response returns the HTTP 403 error code.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

property_name URI xsd:string

The name of the property.

property_name plain xsd:string

The name of the property.

This operation does not return a response body.

Metadata definition objects (since API v2.0) (metadefs, namespaces, objects)

Creates, lists, shows details for, updates, and deletes metadata definition objects.

POST
/v2/metadefs/namespaces/​{namespace_id}​/objects
Create object

Creates an object definition in a namespace.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

namespace plain xsd:string

The namespace is unique across all users.

display_name (Optional) plain xsd:string

User-friendly name to use in a UI to display the namespace name.

description (Optional) plain xsd:string

Detailed description for the namespace.

visibility (Optional) plain xsd:string

Namespace visibility. Valid value is public or private. Default is private.

protected (Optional) plain xsd:boolean

Namespace protection for deletion. Valid value is true or false. Default is false.

properties (Optional) plain xsd:dict

Namespace property definitions, if any.

objects (Optional) plain xsd:dict

Namespace object definitions, if any.

resource_type_associations (Optional) plain xsd:dict

Namespace resource types, if any.

Response parameters
Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User-friendly name to use in a UI to display the namespace name.

description plain xsd:string

The description of the namespace.

visibility plain xsd:string

The namespace visibility. A valid value is public or private. Default is private.

protected plain xsd:string

Namespace protection for deletion. A valid value is True or False. Default is False.

properties plain xsd:string

One or more property definitions for the namespace.

objects plain xsd:string

One or more object definitions of the namespace.

resource_type_associations plain xsd:string

One or more namespace resource types.

{
    "description": "You can configure the CPU limits with control parameters.",
    "name": "CPU Limits",
    "properties": {
        "quota:cpu_period": {
            "description": "Specifies the enforcement interval (unit: microseconds) for QEMU and LXC hypervisors. Within a period, each VCPU of the domain is not allowed to consume more than the quota worth of runtime. The value should be in range [1000, 1000000]. A period with value 0 means no value.",
            "maximum": 1000000,
            "minimum": 1000,
            "title": "Quota: CPU Period",
            "type": "integer"
        },
        "quota:cpu_quota": {
            "description": "Specifies the maximum allowed bandwidth (unit: microseconds). A domain with a negative-value quota indicates that the domain has infinite bandwidth, which means that it is not bandwidth controlled. The value should be in range [1000, 18446744073709551] or less than 0. A quota with value 0 means no value. You can use this feature to ensure that all vCPUs run at the same speed.",
            "title": "Quota: CPU Quota",
            "type": "integer"
        },
        "quota:cpu_shares": {
            "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
            "title": "Quota: CPU Shares",
            "type": "integer"
        }
    },
    "required": []
}
{
    "created_at": "2014-09-19T18:20:56Z",
    "description": "You can configure the CPU limits with control parameters.",
    "name": "CPU Limits",
    "properties": {
        "quota:cpu_period": {
            "description": "Specifies the enforcement interval (unit: microseconds) for QEMU and LXC hypervisors. Within a period, each VCPU of the domain is not allowed to consume more than the quota worth of runtime. The value should be in range [1000, 1000000]. A period with value 0 means no value.",
            "maximum": 1000000,
            "minimum": 1000,
            "title": "Quota: CPU Period",
            "type": "integer"
        },
        "quota:cpu_quota": {
            "description": "Specifies the maximum allowed bandwidth (unit: microseconds). A domain with a negative-value quota indicates that the domain has infinite bandwidth, which means that it is not bandwidth controlled. The value should be in range [1000, 18446744073709551] or less than 0. A quota with value 0 means no value. You can use this feature to ensure that all vCPUs run at the same speed.",
            "title": "Quota: CPU Quota",
            "type": "integer"
        },
        "quota:cpu_shares": {
            "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
            "title": "Quota: CPU Shares",
            "type": "integer"
        }
    },
    "required": [],
    "schema": "/v2/schemas/metadefs/object",
    "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/CPU Limits",
    "updated_at": "2014-09-19T18:20:56Z"
}
GET
/v2/metadefs/namespaces/​{namespace_id}​/objects
List object definitions

Lists object definitions in a namespace.

 

Returns a subset of the larger collection of namespaces and a link that you can use to get the next set of namespaces. 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 namespaces manually, use the limit and marker parameters.

Use the resource_types and visibility query parameters to filter the response.

For example, set the resource_types query parameter to OS::Glance::Image,OS::Nova::Flavor to filter the response to include only namespaces that are associated with the given resource types.

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 namespace attribute is provided as the sort_key.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

visibility (Optional) query imageapi:string

Filters the response by a namespace visibility value.

A valid value is public or private. If you omit this parameter, the response shows public and private namespaces.

resource_types (Optional) query xsd:int

Filters the response by a resource type or types.

Use the comma (,) character to separate multiple values. For example, OS::Glance::Image,OS::Nova::Flavor shows only namespaces for these resource types.

sort_key (Optional) query xsd:string

Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.

sort_dir (Optional) query xsd:string

Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.

Response parameters
Parameter Style Type Description
namespaces plain xsd:list

A list of namespace objects.

namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User-friendly name to use in a UI to display the namespace name.

description plain xsd:string

The description of the namespace.

visibility plain xsd:string

The namespace visibility. A valid value is public or private. Default is private.

protected plain xsd:string

Namespace protection for deletion. A valid value is True or False. Default is False.

resource_type_associations plain xsd:string

One or more namespace resource types.

{
    "objects": [
        {
            "created_at": "2014-09-18T18:16:35Z",
            "description": "You can configure the CPU limits with control parameters.",
            "name": "CPU Limits",
            "properties": {
                "quota:cpu_period": {
                    "description": "Specifies the enforcement interval (unit: microseconds) for QEMU and LXC hypervisors. Within a period, each VCPU of the domain is not allowed to consume more than the quota worth of runtime. The value should be in range [1000, 1000000]. A period with value 0 means no value.",
                    "maximum": 1000000,
                    "minimum": 1000,
                    "title": "Quota: CPU Period",
                    "type": "integer"
                },
                "quota:cpu_quota": {
                    "description": "Specifies the maximum allowed bandwidth (unit: microseconds). A domain with a negative-value quota indicates that the domain has infinite bandwidth, which means that it is not bandwidth controlled. The value should be in range [1000, 18446744073709551] or less than 0. A quota with value 0 means no value. You can use this feature to ensure that all vCPUs run at the same speed.",
                    "title": "Quota: CPU Quota",
                    "type": "integer"
                },
                "quota:cpu_shares": {
                    "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
                    "title": "Quota: CPU Shares",
                    "type": "integer"
                }
            },
            "required": [],
            "schema": "/v2/schemas/metadefs/object",
            "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/CPU Limits"
        },
        {
            "created_at": "2014-09-18T18:16:35Z",
            "description": "Using disk I/O quotas, you can set maximum disk write to 10 MB per second for a VM user.",
            "name": "Disk QoS",
            "properties": {
                "quota:disk_read_bytes_sec": {
                    "description": "Sets disk I/O quota for disk read bytes / sec.",
                    "title": "Quota: Disk read bytes / sec",
                    "type": "integer"
                },
                "quota:disk_read_iops_sec": {
                    "description": "Sets disk I/O quota for disk read IOPS / sec.",
                    "title": "Quota: Disk read IOPS / sec",
                    "type": "integer"
                },
                "quota:disk_total_bytes_sec": {
                    "description": "Sets disk I/O quota for total disk bytes / sec.",
                    "title": "Quota: Disk Total Bytes / sec",
                    "type": "integer"
                },
                "quota:disk_total_iops_sec": {
                    "description": "Sets disk I/O quota for disk total IOPS / sec.",
                    "title": "Quota: Disk Total IOPS / sec",
                    "type": "integer"
                },
                "quota:disk_write_bytes_sec": {
                    "description": "Sets disk I/O quota for disk write bytes / sec.",
                    "title": "Quota: Disk Write Bytes / sec",
                    "type": "integer"
                },
                "quota:disk_write_iops_sec": {
                    "description": "Sets disk I/O quota for disk write IOPS / sec.",
                    "title": "Quota: Disk Write IOPS / sec",
                    "type": "integer"
                }
            },
            "required": [],
            "schema": "/v2/schemas/metadefs/object",
            "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/Disk QoS"
        },
        {
            "created_at": "2014-09-18T18:16:35Z",
            "description": "Bandwidth QoS tuning for instance virtual interfaces (VIFs) may be specified with these properties. Incoming and outgoing traffic can be shaped independently. If not specified, no quality of service (QoS) is applied on that traffic direction. So, if you want to shape only the network's incoming traffic, use inbound only (and vice versa). The OpenStack Networking service abstracts the physical implementation of the network, allowing plugins to configure and manage physical resources. Virtual Interfaces (VIF) in the logical model are analogous to physical network interface cards (NICs). VIFs are typically owned a managed by an external service; for instance when OpenStack Networking is used for building OpenStack networks, VIFs would be created, owned, and managed in Nova. VIFs are connected to OpenStack Networking networks via ports. A port is analogous to a port on a network switch, and it has an administrative state. When a VIF is attached to a port the OpenStack Networking API creates an attachment object, which specifies the fact that a VIF with a given identifier is plugged into the port.",
            "name": "Virtual Interface QoS",
            "properties": {
                "quota:vif_inbound_average": {
                    "description": "Network Virtual Interface (VIF) inbound average in kilobytes per second. Specifies average bit rate on the interface being shaped.",
                    "title": "Quota: VIF Inbound Average",
                    "type": "integer"
                },
                "quota:vif_inbound_burst": {
                    "description": "Network Virtual Interface (VIF) inbound burst in total kilobytes. Specifies the amount of bytes that can be burst at peak speed.",
                    "title": "Quota: VIF Inbound Burst",
                    "type": "integer"
                },
                "quota:vif_inbound_peak": {
                    "description": "Network Virtual Interface (VIF) inbound peak in kilobytes per second. Specifies maximum rate at which an interface can receive data.",
                    "title": "Quota: VIF Inbound Peak",
                    "type": "integer"
                },
                "quota:vif_outbound_average": {
                    "description": "Network Virtual Interface (VIF) outbound average in kilobytes per second. Specifies average bit rate on the interface being shaped.",
                    "title": "Quota: VIF Outbound Average",
                    "type": "integer"
                },
                "quota:vif_outbound_burst": {
                    "description": "Network Virtual Interface (VIF) outbound burst in total kilobytes. Specifies the amount of bytes that can be burst at peak speed.",
                    "title": "Quota: VIF Outbound Burst",
                    "type": "integer"
                },
                "quota:vif_outbound_peak": {
                    "description": "Network Virtual Interface (VIF) outbound peak in kilobytes per second. Specifies maximum rate at which an interface can send data.",
                    "title": "Quota: VIF Outbound Burst",
                    "type": "integer"
                }
            },
            "required": [],
            "schema": "/v2/schemas/metadefs/object",
            "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/Virtual Interface QoS"
        }
    ],
    "schema": "v2/schemas/metadefs/objects"
}
GET
/v2/metadefs/namespaces/​{namespace_id}​/objects/​{object_name}​
Show object definition

Shows the definition for an object.

 

The response body shows a single object entity.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

object_name URI xsd:string

The name of the object.

{
    "created_at": "2014-09-19T18:20:56Z",
    "description": "You can configure the CPU limits with control parameters.",
    "name": "CPU Limits",
    "properties": {
        "quota:cpu_period": {
            "description": "Specifies the enforcement interval (unit: microseconds) for QEMU and LXC hypervisors. Within a period, each VCPU of the domain is not allowed to consume more than the quota worth of runtime. The value should be in range [1000, 1000000]. A period with value 0 means no value.",
            "maximum": 1000000,
            "minimum": 1000,
            "title": "Quota: CPU Period",
            "type": "integer"
        },
        "quota:cpu_quota": {
            "description": "Specifies the maximum allowed bandwidth (unit: microseconds). A domain with a negative-value quota indicates that the domain has infinite bandwidth, which means that it is not bandwidth controlled. The value should be in range [1000, 18446744073709551] or less than 0. A quota with value 0 means no value. You can use this feature to ensure that all vCPUs run at the same speed.",
            "title": "Quota: CPU Quota",
            "type": "integer"
        },
        "quota:cpu_shares": {
            "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
            "title": "Quota: CPU Shares",
            "type": "integer"
        }
    },
    "required": [],
    "schema": "/v2/schemas/metadefs/object",
    "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/CPU Limits",
    "updated_at": "2014-09-19T18:20:56Z"
}

This operation does not accept a request body.

PUT
/v2/metadefs/namespaces/​{namespace_id}​/objects/​{object_name}​
Update object definition

Updates an object definition in a namespace.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

object_name URI xsd:string

The name of the object.

{
    "description": "You can configure the CPU limits with control parameters.",
    "name": "CPU Limits",
    "properties": {
        "quota:cpu_shares": {
            "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
            "title": "Quota: CPU Shares",
            "type": "integer"
        }
    },
    "required": []
}
{
    "created_at": "2014-09-19T19:20:56Z",
    "description": "You can configure the CPU limits with control parameters.",
    "name": "CPU Limits",
    "properties": {
        "quota:cpu_shares": {
            "description": "Specifies the proportional weighted share for the domain. If this element is omitted, the service defaults to the OS provided defaults. There is no unit for the value; it is a relative measure based on the setting of other VMs. For example, a VM configured with value 2048 gets twice as much CPU time as a VM configured with value 1024.",
            "title": "Quota: CPU Shares",
            "type": "integer"
        }
    },
    "required": [],
    "schema": "/v2/schemas/metadefs/object",
    "self": "/v2/metadefs/namespaces/OS::Compute::Quota/objects/CPU Limits",
    "updated_at": "2014-09-19T19:20:56Z"
}
DELETE
/v2/metadefs/namespaces/​{namespace_id}​/objects/​{object_name}​
Delete property definition

Deletes an object definition from a namespace.

 

To delete a protected object from a namespace, you must first set the protected attribute to false (boolean) on the namespace and then perform the delete. If you try to delete a protected object, the call returns the 403 response code.

When you successfully delete an object from a namespace, the response is empty and and the response code is 204.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

object_name URI xsd:string

The name of the object.

This operation does not accept a request body and does not return a response body.

Metadata definition tags (since API v2.0) (metadefs, namespaces, tags)

Creates, lists, shows details for, updates, and deletes metadata definition tags.

POST
/v2/metadefs/namespaces/tags/​{namespace_id}​
Create tags

Creates one or more tag definitions in a namespace.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

namespace plain xsd:string

The namespace is unique across all users.

tags plain xsd:list

A list of tag objects.

name plain xsd:string

The name of the tag.

Response parameters
Parameter Style Type Description
tags plain xsd:list

A list of tag objects.

name plain xsd:string

The name of the tag.

{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}
{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}
GET
/v2/metadefs/namespaces/tags/​{namespace_id}​
List tags

Lists the tag definitions within a namespace.

 

To manually paginate through the list of tags, use the limit and marker parameters.

To sort the results of this operation use the sort_key and sort_dir parameters. The API uses the natural sort order of the tag attribute of the sort_key parameter.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

namespace plain xsd:string

The namespace is unique across all users.

limit (Optional) query xsd:int

Requests a page size of items. Returns a number of items up to a 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

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.

sort_key (Optional) query xsd:string

Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.

sort_dir (Optional) query xsd:string

Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.

Response parameters
Parameter Style Type Description
tags plain xsd:list

A list of tag objects.

name plain xsd:string

The name of the tag.

{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}
DELETE
/v2/metadefs/namespaces/tags/​{namespace_id}​
Delete all tag definitions

Deletes all tag definitions within a namespace.

 

You cannot delete tags in a namespace with the 'protected' attribute set to true (boolean); the response returns the HTTP 403 status code.

You must first set the protected attribute to false (boolean) on the namespace and then perform the delete. The response is empty and returns the HTTP 204 status code.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

namespace plain xsd:string

The namespace is unique across all users.

This operation does not return a response body.

POST
/v2/metadefs/namespaces/tags/​{namespace_id}​/​{tag_name}​
Add tag definition

Adds a tag to the list of namespace tag definitions.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

tag_name URI xsd:string

The name of the tag.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the tag.

{
    "created_at": "2015-05-09T01:12:31Z",
    "name": "added-sample-tag",
    "updated_at": "2015-05-09T01:12:31Z"
}

This operation does not accept a request body.

GET
/v2/metadefs/namespaces/tags/​{namespace_id}​/​{tag_name}​
Get tag definition

Gets a definition for a tag.

 

The response body shows a single tag entity.

Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

tag_name URI xsd:string

The name of the tag.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the tag.

{
    "created_at": "2015-05-06T23:16:12Z",
    "name": "sample-tag2",
    "updated_at": "2015-05-06T23:16:12Z"
}

This operation does not accept a request body.

PUT
/v2/metadefs/namespaces/tags/​{namespace_id}​/​{tag_name}​
Update tag definition

Renames a tag definition.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

tag_name URI xsd:string

The name of the tag.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the tag.

{
    "name": "new-tag-name"
}
{
    "name": "new-tag-name"
}
DELETE
/v2/metadefs/namespaces/tags/​{namespace_id}​/​{tag_name}​
Delete tag definition

Deletes a tag definition within a namespace.

 

You cannot delete tags in a namespace with the 'protected' attribute set to true (boolean); the response returns the HTTP 403 status code.

You must first set the protected attribute to false (boolean) on the namespace and then perform the delete. The response is empty and returns the HTTP 204 status code.

Normal response codes
204
Error response codes
403
Request parameters
Parameter Style Type Description
namespace_id URI csapi:UUID

The UUID of the namespace.

tag_name URI xsd:string

The name of the tag.

This operation does not accept a request body and does not return a response body.

Metadata definition schemas (schemas, metadefs, namespace, namespaces, object, objects, property, properties, tag, tags, resource_type, resource_types)

Gets a JSON-schema document that represents a metadata definition entity.

GET
/v2/schemas/metadefs/namespace
Show metadata definition namespace schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition namespace entity.

 

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "additionalProperties": false,
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "property": {
            "additionalProperties": {
                "properties": {
                    "additionalItems": {
                        "type": "boolean"
                    },
                    "default": {},
                    "description": {
                        "type": "string"
                    },
                    "enum": {
                        "type": "array"
                    },
                    "items": {
                        "properties": {
                            "enum": {
                                "type": "array"
                            },
                            "type": {
                                "enum": [
                                    "array",
                                    "boolean",
                                    "integer",
                                    "number",
                                    "object",
                                    "string",
                                    null
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "maxItems": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maxLength": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maximum": {
                        "type": "number"
                    },
                    "minItems": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minLength": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minimum": {
                        "type": "number"
                    },
                    "name": {
                        "type": "string"
                    },
                    "pattern": {
                        "format": "regex",
                        "type": "string"
                    },
                    "readonly": {
                        "type": "boolean"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "title": {
                        "type": "string"
                    },
                    "type": {
                        "enum": [
                            "array",
                            "boolean",
                            "integer",
                            "number",
                            "object",
                            "string",
                            null
                        ],
                        "type": "string"
                    },
                    "uniqueItems": {
                        "default": false,
                        "type": "boolean"
                    }
                },
                "required": [
                    "title",
                    "type"
                ],
                "type": "object"
            },
            "type": "object"
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "uniqueItems": true
        }
    },
    "name": "namespace",
    "properties": {
        "created_at": {
            "description": "Date and time of namespace creation (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        },
        "description": {
            "description": "Provides a user friendly description of the namespace.",
            "maxLength": 500,
            "type": "string"
        },
        "display_name": {
            "description": "The user friendly name for the namespace. Used by UI if available.",
            "maxLength": 80,
            "type": "string"
        },
        "namespace": {
            "description": "The unique namespace text.",
            "maxLength": 80,
            "type": "string"
        },
        "objects": {
            "items": {
                "properties": {
                    "description": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "properties": {
                        "$ref": "#/definitions/property"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    }
                },
                "type": "object"
            },
            "type": "array"
        },
        "owner": {
            "description": "Owner of the namespace.",
            "maxLength": 255,
            "type": "string"
        },
        "properties": {
            "$ref": "#/definitions/property"
        },
        "protected": {
            "description": "If true, namespace will not be deletable.",
            "type": "boolean"
        },
        "resource_type_associations": {
            "items": {
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "prefix": {
                        "type": "string"
                    },
                    "properties_target": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        },
        "self": {
            "type": "string"
        },
        "updated_at": {
            "description": "Date and time of the last namespace modification (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        },
        "visibility": {
            "description": "Scope of namespace accessibility.",
            "enum": [
                "public",
                "private"
            ],
            "type": "string"
        }
    },
    "required": [
        "namespace"
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/namespaces
Show metadata definition namespaces schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition namespaces entity.

 

A namespaces entity is a container for namespace entities.

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "property": {
            "additionalProperties": {
                "properties": {
                    "additionalItems": {
                        "type": "boolean"
                    },
                    "default": {},
                    "description": {
                        "type": "string"
                    },
                    "enum": {
                        "type": "array"
                    },
                    "items": {
                        "properties": {
                            "enum": {
                                "type": "array"
                            },
                            "type": {
                                "enum": [
                                    "array",
                                    "boolean",
                                    "integer",
                                    "number",
                                    "object",
                                    "string",
                                    null
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "maxItems": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maxLength": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maximum": {
                        "type": "number"
                    },
                    "minItems": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minLength": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minimum": {
                        "type": "number"
                    },
                    "name": {
                        "type": "string"
                    },
                    "pattern": {
                        "format": "regex",
                        "type": "string"
                    },
                    "readonly": {
                        "type": "boolean"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "title": {
                        "type": "string"
                    },
                    "type": {
                        "enum": [
                            "array",
                            "boolean",
                            "integer",
                            "number",
                            "object",
                            "string",
                            null
                        ],
                        "type": "string"
                    },
                    "uniqueItems": {
                        "default": false,
                        "type": "boolean"
                    }
                },
                "required": [
                    "title",
                    "type"
                ],
                "type": "object"
            },
            "type": "object"
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "uniqueItems": true
        }
    },
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "namespaces",
    "properties": {
        "first": {
            "type": "string"
        },
        "namespaces": {
            "items": {
                "additionalProperties": false,
                "name": "namespace",
                "properties": {
                    "created_at": {
                        "description": "Date and time of namespace creation (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    },
                    "description": {
                        "description": "Provides a user friendly description of the namespace.",
                        "maxLength": 500,
                        "type": "string"
                    },
                    "display_name": {
                        "description": "The user friendly name for the namespace. Used by UI if available.",
                        "maxLength": 80,
                        "type": "string"
                    },
                    "namespace": {
                        "description": "The unique namespace text.",
                        "maxLength": 80,
                        "type": "string"
                    },
                    "objects": {
                        "items": {
                            "properties": {
                                "description": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "properties": {
                                    "$ref": "#/definitions/property"
                                },
                                "required": {
                                    "$ref": "#/definitions/stringArray"
                                }
                            },
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "owner": {
                        "description": "Owner of the namespace.",
                        "maxLength": 255,
                        "type": "string"
                    },
                    "properties": {
                        "$ref": "#/definitions/property"
                    },
                    "protected": {
                        "description": "If true, namespace will not be deletable.",
                        "type": "boolean"
                    },
                    "resource_type_associations": {
                        "items": {
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "prefix": {
                                    "type": "string"
                                },
                                "properties_target": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "schema": {
                        "type": "string"
                    },
                    "self": {
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Date and time of the last namespace modification (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    },
                    "visibility": {
                        "description": "Scope of namespace accessibility.",
                        "enum": [
                            "public",
                            "private"
                        ],
                        "type": "string"
                    }
                },
                "required": [
                    "namespace"
                ]
            },
            "type": "array"
        },
        "next": {
            "type": "string"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/object
Show metadata definition object schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition object entity.

 

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "additionalProperties": false,
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "property": {
            "additionalProperties": {
                "properties": {
                    "additionalItems": {
                        "type": "boolean"
                    },
                    "default": {},
                    "description": {
                        "type": "string"
                    },
                    "enum": {
                        "type": "array"
                    },
                    "items": {
                        "properties": {
                            "enum": {
                                "type": "array"
                            },
                            "type": {
                                "enum": [
                                    "array",
                                    "boolean",
                                    "integer",
                                    "number",
                                    "object",
                                    "string",
                                    null
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "maxItems": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maxLength": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maximum": {
                        "type": "number"
                    },
                    "minItems": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minLength": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minimum": {
                        "type": "number"
                    },
                    "name": {
                        "type": "string"
                    },
                    "pattern": {
                        "format": "regex",
                        "type": "string"
                    },
                    "readonly": {
                        "type": "boolean"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "title": {
                        "type": "string"
                    },
                    "type": {
                        "enum": [
                            "array",
                            "boolean",
                            "integer",
                            "number",
                            "object",
                            "string",
                            null
                        ],
                        "type": "string"
                    },
                    "uniqueItems": {
                        "default": false,
                        "type": "boolean"
                    }
                },
                "required": [
                    "title",
                    "type"
                ],
                "type": "object"
            },
            "type": "object"
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "uniqueItems": true
        }
    },
    "name": "object",
    "properties": {
        "created_at": {
            "description": "Date and time of object creation (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "properties": {
            "$ref": "#/definitions/property"
        },
        "required": {
            "$ref": "#/definitions/stringArray"
        },
        "schema": {
            "type": "string"
        },
        "self": {
            "type": "string"
        },
        "updated_at": {
            "description": "Date and time of the last object modification (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        }
    },
    "required": [
        "name"
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/objects
Show metadata definition objects schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition objects entity.

 

An objects entity is a container for object entities.

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "property": {
            "additionalProperties": {
                "properties": {
                    "additionalItems": {
                        "type": "boolean"
                    },
                    "default": {},
                    "description": {
                        "type": "string"
                    },
                    "enum": {
                        "type": "array"
                    },
                    "items": {
                        "properties": {
                            "enum": {
                                "type": "array"
                            },
                            "type": {
                                "enum": [
                                    "array",
                                    "boolean",
                                    "integer",
                                    "number",
                                    "object",
                                    "string",
                                    null
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "maxItems": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maxLength": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maximum": {
                        "type": "number"
                    },
                    "minItems": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minLength": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minimum": {
                        "type": "number"
                    },
                    "name": {
                        "type": "string"
                    },
                    "pattern": {
                        "format": "regex",
                        "type": "string"
                    },
                    "readonly": {
                        "type": "boolean"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "title": {
                        "type": "string"
                    },
                    "type": {
                        "enum": [
                            "array",
                            "boolean",
                            "integer",
                            "number",
                            "object",
                            "string",
                            null
                        ],
                        "type": "string"
                    },
                    "uniqueItems": {
                        "default": false,
                        "type": "boolean"
                    }
                },
                "required": [
                    "title",
                    "type"
                ],
                "type": "object"
            },
            "type": "object"
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "uniqueItems": true
        }
    },
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "objects",
    "properties": {
        "first": {
            "type": "string"
        },
        "next": {
            "type": "string"
        },
        "objects": {
            "items": {
                "additionalProperties": false,
                "name": "object",
                "properties": {
                    "created_at": {
                        "description": "Date and time of object creation (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "properties": {
                        "$ref": "#/definitions/property"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "schema": {
                        "type": "string"
                    },
                    "self": {
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Date and time of the last object modification (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    }
                },
                "required": [
                    "name"
                ]
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/property
Show metadata definition property schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition property entity.

 

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "additionalProperties": false,
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
        }
    },
    "name": "property",
    "properties": {
        "additionalItems": {
            "type": "boolean"
        },
        "default": {},
        "description": {
            "type": "string"
        },
        "enum": {
            "type": "array"
        },
        "items": {
            "properties": {
                "enum": {
                    "type": "array"
                },
                "type": {
                    "enum": [
                        "array",
                        "boolean",
                        "integer",
                        "number",
                        "object",
                        "string",
                        null
                    ],
                    "type": "string"
                }
            },
            "type": "object"
        },
        "maxItems": {
            "$ref": "#/definitions/positiveInteger"
        },
        "maxLength": {
            "$ref": "#/definitions/positiveInteger"
        },
        "maximum": {
            "type": "number"
        },
        "minItems": {
            "$ref": "#/definitions/positiveIntegerDefault0"
        },
        "minLength": {
            "$ref": "#/definitions/positiveIntegerDefault0"
        },
        "minimum": {
            "type": "number"
        },
        "name": {
            "type": "string"
        },
        "pattern": {
            "format": "regex",
            "type": "string"
        },
        "readonly": {
            "type": "boolean"
        },
        "required": {
            "$ref": "#/definitions/stringArray"
        },
        "title": {
            "type": "string"
        },
        "type": {
            "enum": [
                "array",
                "boolean",
                "integer",
                "number",
                "object",
                "string",
                null
            ],
            "type": "string"
        },
        "uniqueItems": {
            "default": false,
            "type": "boolean"
        }
    },
    "required": [
        "type",
        "title",
        "name"
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/properties
Show metadata definition properties schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition properties entity.

 

A properties entity is a container for property entities.

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "definitions": {
        "positiveInteger": {
            "minimum": 0,
            "type": "integer"
        },
        "positiveIntegerDefault0": {
            "allOf": [
                {
                    "$ref": "#/definitions/positiveInteger"
                },
                {
                    "default": 0
                }
            ]
        },
        "stringArray": {
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
        }
    },
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "properties",
    "properties": {
        "first": {
            "type": "string"
        },
        "next": {
            "type": "string"
        },
        "properties": {
            "additionalProperties": {
                "additionalProperties": false,
                "name": "property",
                "properties": {
                    "additionalItems": {
                        "type": "boolean"
                    },
                    "default": {},
                    "description": {
                        "type": "string"
                    },
                    "enum": {
                        "type": "array"
                    },
                    "items": {
                        "properties": {
                            "enum": {
                                "type": "array"
                            },
                            "type": {
                                "enum": [
                                    "array",
                                    "boolean",
                                    "integer",
                                    "number",
                                    "object",
                                    "string",
                                    null
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "maxItems": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maxLength": {
                        "$ref": "#/definitions/positiveInteger"
                    },
                    "maximum": {
                        "type": "number"
                    },
                    "minItems": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minLength": {
                        "$ref": "#/definitions/positiveIntegerDefault0"
                    },
                    "minimum": {
                        "type": "number"
                    },
                    "name": {
                        "type": "string"
                    },
                    "pattern": {
                        "format": "regex",
                        "type": "string"
                    },
                    "readonly": {
                        "type": "boolean"
                    },
                    "required": {
                        "$ref": "#/definitions/stringArray"
                    },
                    "title": {
                        "type": "string"
                    },
                    "type": {
                        "enum": [
                            "array",
                            "boolean",
                            "integer",
                            "number",
                            "object",
                            "string",
                            null
                        ],
                        "type": "string"
                    },
                    "uniqueItems": {
                        "default": false,
                        "type": "boolean"
                    }
                },
                "required": [
                    "type",
                    "title"
                ]
            },
            "type": "object"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/tag
Show metadata definition tag schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition tag entity.

 

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "additionalProperties": false,
    "required": [
        "name"
    ],
    "name": "tag",
    "properties": {
        "created_at": {
            "type": "string",
            "description": "Date and time of tag creation (READ-ONLY)",
            "format": "date-time"
        },
        "name": {
            "type": "string"
        },
        "updated_at": {
            "type": "string",
            "description": "Date and time of the last tag modification (READ-ONLY)",
            "format": "date-time"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/tags
Show metadata definition tags schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition tags entity.

 

A tags entity is a container for tag entities.

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "name": "tags",
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "properties": {
        "next": {
            "type": "string"
        },
        "schema": {
            "type": "string"
        },
        "first": {
            "type": "string"
        },
        "tags": {
            "items": {
                "additionalProperties": false,
                "required": [
                    "name"
                ],
                "name": "tag",
                "properties": {
                    "created_at": {
                        "type": "string",
                        "description": "Date and time of tag creation (READ-ONLY)",
                        "format": "date-time"
                    },
                    "name": {
                        "type": "string"
                    },
                    "updated_at": {
                        "type": "string",
                        "description": "Date and time of the last tag modification (READ-ONLY)",
                        "format": "date-time"
                    }
                }
            },
            "type": "array"
        }
    }
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/resource_type
Show metadata definition namespace resource type association schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition namespace resource type association entity.

 

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "additionalProperties": false,
    "name": "resource_type_association",
    "properties": {
        "created_at": {
            "description": "Date and time of resource type association (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        },
        "name": {
            "description": "Resource type names should be aligned with Heat resource types whenever possible: http://docs.openstack.org/developer/heat/template_guide/openstack.html",
            "maxLength": 80,
            "type": "string"
        },
        "prefix": {
            "description": "Specifies the prefix to use for the given resource type. Any properties in the namespace should be prefixed with this prefix when being applied to the specified resource type. Must include prefix separator (e.g. a colon :). It is important to note that the same base property key can require different prefixes depending on the target resource type. For example: The desired virtual CPU topology can be set on both images and flavors via metadata. The keys have different prefixes on images than on flavors On flavors keys are prefixed with 'hw:', but on images the keys are prefixed with 'hw_'.",
            "maxLength": 80,
            "type": "string"
        },
        "properties_target": {
            "description": "Some resource types allow more than one key / value pair per instance.  For example, Cinder allows user and image metadata on volumes. Only the image properties metadata is evaluated by Nova (scheduling or drivers). This property allows a namespace target to remove the ambiguity.",
            "maxLength": 80,
            "type": "string"
        },
        "updated_at": {
            "description": "Date and time of the last resource type association modification (READ-ONLY)",
            "format": "date-time",
            "type": "string"
        }
    },
    "required": [
        "name"
    ]
}

This operation does not accept a request body.

GET
/v2/schemas/metadefs/resource_types
Show metadata definition namespace resource type associations schema

(Since API v2.1) Shows a JSON schema document that represents a metadata definition namespace resource type associations entity.

 

A resource type associations entity is a container for resource type association entities.

The following schema document is an example. The authoritative response is the actual response to the API call.

Normal response codes
200
{
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "resource_type_associations",
    "properties": {
        "first": {
            "type": "string"
        },
        "next": {
            "type": "string"
        },
        "resource_type_associations": {
            "items": {
                "additionalProperties": false,
                "name": "resource_type_association",
                "properties": {
                    "created_at": {
                        "description": "Date and time of resource type association (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    },
                    "name": {
                        "description": "Resource type names should be aligned with Heat resource types whenever possible: http://docs.openstack.org/developer/heat/template_guide/openstack.html",
                        "maxLength": 80,
                        "type": "string"
                    },
                    "prefix": {
                        "description": "Specifies the prefix to use for the given resource type. Any properties in the namespace should be prefixed with this prefix when being applied to the specified resource type. Must include prefix separator (e.g. a colon :). It is important to note that the same base property key can require different prefixes depending on the target resource type. For example: The desired virtual CPU topology can be set on both images and flavors via metadata. The keys have different prefixes on images than on flavors On flavors keys are prefixed with 'hw:', but on images the keys are prefixed with 'hw_'.",
                        "maxLength": 80,
                        "type": "string"
                    },
                    "properties_target": {
                        "description": "Some resource types allow more than one key / value pair per instance.  For example, Cinder allows user and image metadata on volumes. Only the image properties metadata is evaluated by Nova (scheduling or drivers). This property allows a namespace target to remove the ambiguity.",
                        "maxLength": 80,
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Date and time of the last resource type association modification (READ-ONLY)",
                        "format": "date-time",
                        "type": "string"
                    }
                },
                "required": [
                    "name"
                ]
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        }
    }
}

This operation does not accept a request body.

Tasks (since API v2.2) (tasks)

Creates, lists, and shows details for tasks.

POST
/v2/tasks
Create task

Creates a task.

 
Normal response codes
201
{
    "type": "import",
    "input": {
        "import_from": "http://example.com",
        "import_from_format": "qcow2",
        "image_properties": {
            "disk_format": "vhd",
            "container_format": "ovf"
        }
    }
}

This operation does not return a response body.

GET
/v2/tasks
List tasks

Lists tasks.

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

Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.

sort_key (Optional) query xsd:string

Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.

type (Optional) query xsd:string

Filters the response by a task type. A valid value is import.

status (Optional) query xsd:string

Filters the response by a task status. A valid value is pending, processing, success, or failure.

{
    "tasks": [
        {
            "id": "cbc36478b0bd8e67e89469c7749d4127",
            "type": "import",
            "status": "pending"
        },
        {
            "id": "bbc36578b0bd8e67e89469c7749d4126",
            "type": "import",
            "status": "processing"
        }
    ]
}
GET
/v2/tasks/​{task_id}​
Show task details

Shows details for a task.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
task_id URI csapi:UUID

The UUID of the task.

task_id plain csapi:UUID

The UUID of the task.

{
    "id": "e7e59ff6-fa2e-4075-87d3-1a1398a07dc3",
    "type": "import",
    "status": "pending"
}