Image service API v2

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

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

API versions

GET
/
List API versions

Lists information about all Image service API versions.

 
Normal response codes
200, 300

Example Responses

{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v2.2",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.1",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "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.

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 has not uploaded 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 error occurred during the upload of image data.

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.

POST
/v2/images
Create image

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

 

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

Synchronous Postconditions

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

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

Normal response codes
201

Request parameters

Parameter Style Type Description
name plain xsd:string

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

id (Optional) plain csapi:uuid

The image ID.

visibility (Optional) plain xsd:string

Image visibility. Public or private. Default is public.

tags (Optional) plain xsd:dict

Image tags.
container_format (Optional) plain xsd:string

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

disk_format (Optional) plain xsd:string

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

If true, image is not deletable.
properties (Optional) plain xsd:dict

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

Response parameters

Parameter Style Type Description
status plain xsd:string

The image status.
container_format plain xsd:string

The container format of image.

If this field has no value, its value is null (JSON null data type).

min_ram plain csapi:uuid

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

If this field has no value, its value is null (JSON null data type).

updated_at plain xsd:datetime

The date and time when the image was last updated.
owner plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

min_disk plain xsd:int

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

If this field has no value, its value is null (JSON null data type).

tags plain xsd:dict

Image tags.
visibility plain xsd:boolean

The image visibility.
id plain csapi:uuid

The unique ID for the image.
size plain xsd:int

The size of the image data, in bytes.

If this field has no value, its value is null (JSON null data type).

virtual_size plain xsd:int

The virtual size of the image.

If this field has no value, its value is null (JSON null data type).

name plain xsd:string

The name of the image.

If this field has no value, its value is null (JSON null data type).

checksum plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

created_at plain xsd:datetime

The date and time when the image was created.
disk_format plain xsd:string

The disk format of the image.

If this field has no value, its value is null (JSON null data type).

properties plain xsd:dict

Properties, if any, that are associated with the image.
protected plain xsd:boolean

Indicates whether the image can be deleted.
location header xsd:string

URL to access the image file kept in external store.
self plain xsd:string

URL for the virtual machine image.
file plain xsd:string

URL for the virtual machine image file.
schema plain xsd:string

URL for schema of the virtual machine image.

Example Requests

{
    "name": "Ubuntu 12.10",
    "tags": [
        "ubuntu",
        "quantal"
    ],
    "container_format": "bare",
    "disk_format": "qcow2",
    "visibility": "private",
    "min_disk": 0,
    "protected": false,
    "min_ram": 0
}

Example Responses

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

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

 

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

The list operation accepts several types of query parameters that let you filter the results of the returned collection.

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

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

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

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

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

  • sort_key. Sorts by the requested image attribute. Sorts in the natural sorting direction of the image attribute that is provided as the sort_key.

  • sort_dir. Sorts in a specified sort direction.

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

To specify the sort_key and sort_dir query parameters to sort the results: 

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

To specify the sort query parameter to sort the results: 

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

marker (Optional) query xsd:string

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

name (Optional) query xsd:string

Filter parameter.

Shows only images with the specified name.

A valid value is the name of the image as a string.

visibility (Optional) query imageapi:string

Filter parameter.

Shows only images with the specified image visibility value or values.

Valid values are public, private, and shared. If you omit this parameter, the response shows public, private, and shared images with accepted member status.

member_status (Optional) query imageapi:string

Filter parameter.

Shows only images with the specified member status.

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

owner (Optional) query imageapi:string

Filter parameter.

Shows only images that are shared with the specified owner.

A valid value is a tenant ID.

status (Optional) query xsd:int

Filter parameter.

Shows only images with the specified image status.

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

size_min (Optional) query xsd:string

Filter parameter.

Shows only images with the specified minimum image size.

A valid value is the minimum size of the image, in bytes.

size_max (Optional) query xsd:string

Filter parameter.

Shows only images with the specified maximum image size.

A valid valud is the maximum size of the image, in bytes.

sort_key (Optional) query xsd:string

Sorts by the requested image attribute. Accepted values are name, status, container_format, disk_format, size, id, created_at, and updated_at. Default is created_at. The API uses the natural sorting direction of the image attribute that is provided as the sort_key.

sort_dir (Optional) query xsd:string

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

sort (Optional) query xsd:string

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

For example:

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

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

Response parameters

Parameter Style Type Description
images plain xsd:string

An images object.

status plain xsd:string

The image status.
name plain xsd:string

The name of the image.

If this field has no value, its value is null (JSON null data type).

tags plain xsd:dict

Image tags.
container_format plain xsd:string

The container format of image.

If this field has no value, its value is null (JSON null data type).

created_at plain xsd:datetime

The date and time when the image was created.
disk_format plain xsd:string

The disk format of the image.

If this field has no value, its value is null (JSON null data type).

updated_at plain xsd:datetime

The date and time when the image was last updated.
min_disk plain xsd:int

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

If this field has no value, its value is null (JSON null data type).

protected plain xsd:boolean

Indicates whether the image can be deleted.
id plain csapi:uuid

The unique ID for the image.
min_ram plain csapi:uuid

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

If this field has no value, its value is null (JSON null data type).

checksum plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

owner plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

visibility plain xsd:boolean

The image visibility.
virtual_size plain xsd:int

The virtual size of the image.

If this field has no value, its value is null (JSON null data type).

size plain xsd:int

The size of the image data, in bytes.

If this field has no value, its value is null (JSON null data type).

properties plain xsd:dict

Properties, if any, that are associated with the image.
url plain xsd:string

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

metadata plain xsd:dict

The location metadata.
direct_url plain xsd:string

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

self plain xsd:string

URL for the virtual machine image.
file plain xsd:string

URL for the virtual machine image file.
schema plain xsd:string

URL for schema of the virtual machine image.
schema plain xsd:string

URL for schema of the virtual machine images.
first plain xsd:string

URL for the first page of response.

Example Responses

{
    "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"
}
GET
/v2/images/​{image_id}​
Get image details

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

 

Response body is a single image entity.

Preconditions

  • The specified image must exist.

Normal response codes
200

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

Response parameters

Parameter Style Type Description
status plain xsd:string

The image status.
name plain xsd:string

The name of the image.

If this field has no value, its value is null (JSON null data type).

tags plain xsd:dict

Image tags.
container_format plain xsd:string

The container format of image.

If this field has no value, its value is null (JSON null data type).

created_at plain xsd:datetime

The date and time when the image was created.
disk_format plain xsd:string

The disk format of the image.

If this field has no value, its value is null (JSON null data type).

updated_at plain xsd:datetime

The date and time when the image was last updated.
min_disk plain xsd:int

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

If this field has no value, its value is null (JSON null data type).

protected plain xsd:boolean

Indicates whether the image can be deleted.
id plain csapi:uuid

The unique ID for the image.
min_ram plain csapi:uuid

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

If this field has no value, its value is null (JSON null data type).

checksum plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

owner plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

visibility plain xsd:boolean

The image visibility.
size plain xsd:int

The size of the image data, in bytes.

If this field has no value, its value is null (JSON null data type).

url plain xsd:string

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

metadata plain xsd:dict

The location metadata.
properties plain xsd:dict

Properties, if any, that are associated with the image.
direct_url plain xsd:string

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

self plain xsd:string

URL for the virtual machine image.
file plain xsd:string

URL for the virtual machine image file.
schema plain xsd:string

URL for schema of the virtual machine image.

Example Responses

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

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

 

Depending on the referenced target location, this operation performs one of the following functions:

  • The target location is an array index. A new value is inserted into the array at the specified index.

  • The target location is an object member that does not exist. A new member is added to the object.

  • The target location is an object member that exists. The member value is replaced.

The operation object MUST contain a value member that specifies 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 specified value is the entire content of the target document.

  • A member to add to an object. The specified value is added to that object at the specified location. If the member already exists, it is replaced by the specified value.

  • An element to add to the array. The specified value is added to the array at the specified location. Any element that is at or above the specified index is shifted one position to the right. The specified index MUST NOT be greater than the number of elements in the array. If the hyphen (-) character is used to index the end of the array (see [RFC6901]), the value is appended to the array.

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 or replace a location to the specified image, you must set the disk_format and container_format parameters in the image.

  • When you replace a location, a 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

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

path plain xsd:string

Image's property.
value plain xsd:string

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

op plain xsd:string

The operation. A valid value is:

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

remove. Removes the specified image's property or location.

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

url plain xsd:string

URL to access the image file kept in external store.

metadata plain xsd:dict

The location metadata.

Response parameters

Parameter Style Type Description
status plain xsd:string

The image status.
name plain xsd:string

The name of the image.

If this field has no value, its value is null (JSON null data type).

tags plain xsd:dict

Image tags.
container_format plain xsd:string

The container format of image.

If this field has no value, its value is null (JSON null data type).

created_at plain xsd:datetime

The date and time when the image was created.
disk_format plain xsd:string

The disk format of the image.

If this field has no value, its value is null (JSON null data type).

updated_at plain xsd:datetime

The date and time when the image was last updated.
min_disk plain xsd:int

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

If this field has no value, its value is null (JSON null data type).

protected plain xsd:boolean

Indicates whether the image can be deleted.
id plain csapi:uuid

The unique ID for the image.
min_ram plain csapi:uuid

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

If this field has no value, its value is null (JSON null data type).

checksum plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

owner plain xsd:string

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

If this field has no value, its value is null (JSON null data type).

visibility plain xsd:boolean

The image visibility.
size plain xsd:int

The size of the image data, in bytes.

If this field has no value, its value is null (JSON null data type).

url plain xsd:string

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

metadata plain xsd:dict

The location metadata.
properties plain xsd:dict

Properties, if any, that are associated with the image.
direct_url plain xsd:string

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

self plain xsd:string

URL for the virtual machine image.
file plain xsd:string

URL for the virtual machine image file.
schema plain xsd:string

URL for schema of the virtual machine image.

Example Requests

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

Example Responses

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

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

 

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

Preconditions

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

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

Synchronous Postconditions

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

  • The image is deleted in images index.

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

TroubleShooting

  • The response returns the HTTP 403 status code when the protected attribute is set to true even if you have 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
403

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

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

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

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

 

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

Preconditions

  • The specified image must exist.

Normal response codes
204

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

Example Responses

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

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

 

If you try to download a deactivated image, the 403 Forbidden error is returned. Also, image locations are not visible for deactivated images unless the user is an administrative user.

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

Preconditions

  • The specified image must exist.

Normal response codes
204

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

Example Responses

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

Uploads and downloads raw image data.

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

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

 

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

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

Preconditions

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

  • The specified 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, your request might lack 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

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

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

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

 

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

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

Preconditions

  • The specified images must exist.

Synchronous Postconditions

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

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

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

Normal response codes
200, 204

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

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

Adds and deletes image tags.

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

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

 
Normal response codes
204

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

tag URI xsd:string

Image tag.

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

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

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

 
Normal response codes
204

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

tag URI xsd:string

Image tag.

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

Members

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

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

 

Preconditions

  • The specified images must exist.

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

  • You must be the owner of the specified image.

Synchronous Postconditions

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

Troubleshooting

  • Even if you have correct permissions, if the visibility attribute is set to public, the request returns the HTTP 403 error code. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.

  • If the specified member is already a member for the image, the service returns the HTTP 409 Conflict error code. In case you meant a different member, double-check that you specified the correct member.

Normal response codes
200
Error response codes
invalidVisibility (403), memberConflict (409)

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

Example Requests

{
    "member": "8989447062e04a818baf9e073fd04fa7"
}

Example Responses

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

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

 

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

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

Preconditions

  • The specified image must exist.

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

Normal response codes
200
Error response codes
404

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

Response parameters

Parameter Style Type Description
schema plain xsd:string

The URL for schema of the members.

Example Responses

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

GET
/v2/images/​{image_id}​/members/​{member_id}​
Show image member details

Shows image member details.

 

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

Preconditions

  • The specified image must exist.

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

Normal response codes
200

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

member_id URI xsd:string

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

Example Responses

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

DELETE
/v2/images/​{image_id}​/members/​{member_id}​
Delete image member

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

 

Preconditions

  • The specified image must exist.

  • You must be the owner of the specified image.

Synchronous Postconditions

  • The specified member is removed from the image members.

Troubleshooting

  • Even if you have correct permissions, if you are not the owner of the specified image, the request returns the HTTP 403 error code. 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

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

member_id URI xsd:string

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

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

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

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

 

Preconditions

  • The specified images must exist.

  • You must be a member of the specified 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 see the updated member status of the image through API calls.

Normal response codes
200

Request parameters

Parameter Style Type Description
image_id URI csapi:uuid

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

member_id URI xsd:string

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

status plain xsd:string

The status of this image member.

Example Requests

{
    "status": "accepted"
}

Example Responses

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

Image schemas

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

GET
/v2/schemas/images
Get images schema

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

 

An images entity is a container of image entities.

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

Normal response codes
200

Example Responses

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

This operation does not accept a request body.

GET
/v2/schemas/image
Get image schema

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

 

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

Normal response codes
200

Example Responses

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

This operation does not accept a request body.

GET
/v2/schemas/members
Get image members schema

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

 

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

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

Normal response codes
200

Example Responses

{
    "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
Get image member schema

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

 

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

Normal response codes
200

Example Responses

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

Lists resource types. Also, creates, lists, and removes resource type associations in a specified namespace. (Since API v2.0.)

GET
/v2/metadefs/resource_types
List resource types

Lists resource types.

 

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

Normal response codes
200

Example Responses

{
    "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}​/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 URI xsd:string

Unique namespace.

name plain xsd:string

Name of the resource type.
prefix (Optional) plain xsd:string

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

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.

Example Requests

{
    "name": "OS::Cinder::Volume",
    "prefix": "hw_",
    "properties_target": "image"
}

Example Responses

{
    "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}​/resource_types
List resource type associations

Lists resource type associations in a specified namespace.

 

The response body lists resource type association entities.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI xsd:string

Unique namespace.

Example Responses

{
    "resource_type_associations": [
        {
            "created_at": "2014-09-19T16:13:33Z",
            "name": "OS::Glance::Image",
            "prefix": "hw_",
            "updated_at": "2014-09-19T16:13:33Z"
        },
        {
            "created_at": "2014-09-19T16:09:13Z",
            "name": "OS::Cinder::Volume",
            "prefix": "hw_",
            "properties_target": "image",
            "updated_at": "2014-09-19T16:09:13Z"
        }
    ]
}

This operation does not accept a request body.

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

Removes a specified resource type association in a specified 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 URI xsd:string

Unique 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

Creates, lists, gets details for, updates, and deletes metadata definition namespaces. Defines namespaces that can contain property definitions, object definitions, and resource type associations. (Since API v2.0.)

POST
/v2/metadefs/namespaces
Create namespace

Creates a namespace.

 

The namespace is created with a Location header that contains the newly-created URI for the namespace.

Normal response codes
201

Request parameters

Parameter Style Type Description
namespace plain xsd:string

A namespace name that is unique across all users.

display_name (Optional) plain xsd:string

User-friendly name that can be used in 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

One or more property definitions in the namespace.

objects (Optional) plain xsd:dict

One or more object definitions in the namespace.

resource_type_associations (Optional) plain xsd:dict

One or more resource types that are associated with this namespace.

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 which could be used in UI for displaying namespace name.
description plain xsd:string

Detailed description for the namespace.
visibility plain xsd:string

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

Property definition(s) of the namespace.
objects plain xsd:string

Object definition(s) of the namespace.
resource_type_associations plain xsd:string

Resource type(s) which are associated with this namespace.

Example Requests

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

Example Responses

{
    "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 let you filter the results in the returned collection.

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

marker (Optional) query xsd:string

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

visibility (Optional) query imageapi:string

Filter parameter. Namespace visibility. Valid values are public and private. Default is public.

resource_types (Optional) query xsd:int

Filter parameter. Specify this value as comma- separated list. For example, send the resource_types filter of OS::Glance::Image,OS::Nova::Flavor to filter the namespaces by the specified resource types.

sort_key (Optional) query xsd:string

Sort key. Use attributes like namespace for sorting. Default is created_at.

sort_dir (Optional) query xsd:string

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

Response parameters

Parameter Style Type Description
namespaces plain xsd:string

A namespaces object.

namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User friendly name which could be used in UI for displaying namespace name.
description plain xsd:string

Detailed description for the namespace.
visibility plain xsd:string

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

Resource type(s) which are associated with this namespace.

Example Responses

{
    "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/content/customize-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}​
Get namespaces details

Gets details for a specified 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 URI xsd:string

Unique namespace.

Example Responses

{
    "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}​
Update namespace

Updates a specified namespace.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI xsd:string

Unique namespace.

namespace URI csapi:uuid

Unique namespace.

Example Requests

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

Example Responses

{
    "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}​
Delete namespace

Deletes a specified 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 status 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.

If the operation succeeds, the response returns the HTTP 204 status 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 error code.

Normal response codes
204
Error response codes
403

Request parameters

Parameter Style Type Description
namespace URI xsd:string

Unique namespace.

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

Metadata definition properties

Creates, lists, gets details for, updates, and deletes metadata definition properties. (Since API v2.0.)

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

Creates a property definition within a namespace.

 

The schema is a subset of JSON property definition schema.

Normal response codes
201

Request 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 (Optional) plain xsd:string

Enumeration 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:string

Enumeration 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).

Example Requests

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

Example Responses

{
    "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}​/properties
List properties

Lists property definitions within a namespace.

 

Returns a list of property definitions in a namespace.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI csapi:uuid

Unique namespace.

Response parameters

Parameter Style Type Description
properties plain xsd:string

A properties object.
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:string

Enumeration 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).

Example Responses

{
    "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"
        }
    }
}
GET
/v2/metadefs/namespaces/​{namespace}​/properties/​{property_name}​
Get property definition

Gets the definition for a specified property.

 

If you include the resource_type query parameter, the prefix of the included resource type is removed from the property name before the query is submitted. This enables you to look for a property name that starts with a prefix from an associated resource type.

Response body shows a single property entity.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI csapi:uuid

Unique namespace.
property_name plain xsd:string

The name of the property.
resource_type (Optional) query xsd:int

Filter parameter.

Shows only property names that start with a prefix from an associated specified resource type.

The prefix of the included resource type is removed 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:string

Enumeration 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).

Example Responses

{
    "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}​/properties/​{property_name}​
Update property definition

Updates a specified property definition.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
name plain xsd:string

Name of the property.

title plain xsd:string

Property title.

type plain xsd:string

Property type

enum (Optional) plain xsd:enum

Enumeration of property values.
items (Optional) plain xsd:dict

specifies schema for the items in an array.

description (Optional) plain xsd:string

Property description.
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:int

Minimum allowed numerical value.
maximum (Optional) plain xsd:dict

Maximum allowed numerical value.
minLength (Optional) plain xsd:dict

Minimum allowed string length.
maxLength (Optional) plain xsd:dict

Maximum allowed string length.
pattern (Optional) plain xsd:dict

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

minItems (Optional) plain xsd:dict

Minimum length of an array.
maxItems (Optional) plain xsd:dict

Maximum length of an array.
uniqueItems (Optional) plain xsd:dict

whether all the values in the array must be distinct.

additionalItems (Optional) plain xsd:dict

If you use tuple-typing, describes extra items. If the value of items is an array and the instance is longer than the list of schemas in items, the schema in this property describes the additional items.

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

A value of true indicates an empty schema, or 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:string

Enumeration 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).

Example Requests

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

Example Responses

{
    "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}​/properties/​{property_name}​
Remove property definition

Removes a specified property definition in a specified 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 URI csapi:uuid

Unique namespace.
property_name plain xsd:string

The name of the property.

This operation does not return a response body.

Metadata definition objects

Creates, lists, gets details for, updates, and deletes metadata definition objects. (Since API v2.0.)

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

Creates an object definition in a specified namespace.

 
Normal response codes
201

Request parameters

Parameter Style Type Description
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. 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

Property definitions, if any, for the namespace.
objects (Optional) plain xsd:dict

Object definitions, if any, for the namespace.
resource_type_associations (Optional) plain xsd:dict

Resource types, if any, that are associated with this namespace

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 which could be used in UI for displaying namespace name.
description plain xsd:string

Detailed description for the namespace.
visibility plain xsd:string

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

Property definition(s) of the namespace.
objects plain xsd:string

Object definition(s) of the namespace.
resource_type_associations plain xsd:string

Resource type(s) which are associated with this namespace.

Example Requests

{
    "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": []
}

Example Responses

{
    "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}​/objects
List objects

Lists object definitions within 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.

The list operation accepts resource_types and visibility as query parameters that let you filter the results of the returned collection.

For example, sending a resource_types filter of OS::Glance::Image,OS::Nova::Flavor filters the namespaces to include only namespaces that are associated to 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
visibility (Optional) query imageapi:string

Filter parameter.

Shows only namespaces with the specified visibility value or values.

Valid values are public and private. If you omit this parameter, the response shows public and private namespaces.

resource_types (Optional) query xsd:int

Filter parameter.

Shows only namespaces with the specified resource type or types.

Specify multiple values as a comma-separated list. For example, set the resource_types filter to OS::Glance::Image,OS::Nova::Flavor to include only namespaces that are associated with the specified resource types.

sort_key (Optional) query xsd:string

Sort key. A valid value is an attribute, such as namespace, for sorting. Default is created_at.

sort_dir (Optional) query xsd:string

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc.

Response parameters

Parameter Style Type Description
namespaces plain xsd:string

A namespaces object.

namespace plain xsd:string

The namespace is unique across all users.

display_name plain xsd:string

User friendly name which could be used in UI for displaying namespace name.
description plain xsd:string

Detailed description for the namespace.
visibility plain xsd:string

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

Resource type(s) which are associated with this namespace.

Example Responses

{
    "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}​/objects/​{object_name}​
Get object definition

Gets definition for a specified object.

 

Response body is a single object entity.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI csapi:uuid

Unique namespace.
object_name URI xsd:string

The name of the object.
namespace URI csapi:uuid

Unique namespace.

Example Responses

{
    "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"
}
PUT
/v2/metadefs/namespaces/​{namespace}​/objects/​{object_name}​
Update object definition

Updates a specified object definition in a specified namespace.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
namespace URI csapi:uuid

Unique namespace.
object_name URI xsd:string

The name of the object.

Example Requests

{
    "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": []
}

Example Responses

{
    "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}​/objects/​{object_name}​
Delete property definition

Deletes a specified object definition within a namespace.

 

You cannot delete objects 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 URI csapi:uuid

Unique namespace.
object_name URI xsd:string

The name of the object.

This operation does not return a response body.

Metadata definition tags

Creates, lists, gets details for, updates, and deletes metadata definition tags. (Since API v2.0.)

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

Creates one or more tag definitions in a specified namespace.

 
Normal response codes
201

Request parameters

Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

tags plain xsd:string

A list of tag dictionary objects.

name plain xsd:string

Name of the tag.

Response parameters

Parameter Style Type Description
tags plain xsd:string

A list of tag dictionary objects.

name plain xsd:string

Name of the tag.

Example Requests

{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}

Example Responses

{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}
GET
/v2/metadefs/namespaces/​{namespace}​/tags
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 specified sort_key parameter.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

limit (Optional) query xsd:int

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

marker (Optional) query xsd:string

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

sort_key (Optional) query xsd:string

Sort key. A valid value is an attribute, such as name. for sorting. Default is created_at.

sort_dir (Optional) query xsd:string

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc.

Response parameters

Parameter Style Type Description
tags plain xsd:string

A list of tag dictionary objects.

name plain xsd:string

Name of the tag.

Example Responses

{
    "tags": [
        {
            "name": "sample-tag1"
        },
        {
            "name": "sample-tag2"
        },
        {
            "name": "sample-tag3"
        }
    ]
}
DELETE
/v2/metadefs/namespaces/​{namespace}​/tags
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 plain xsd:string

The namespace is unique across all users.

This operation does not return a response body.

POST
/v2/metadefs/namespaces/​{namespace}​/tags/​{name}​
Add tag definition

Adds a specified tag to the list of namespace tag definitions.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

name plain xsd:string

Name of the tag.

Response parameters

Parameter Style Type Description
name plain xsd:string

Name of the tag.

Example Responses

{
    "created_at": "2015-05-09T01:12:31Z",
    "name": "added-sample-tag",
    "updated_at": "2015-05-09T01:12:31Z"
}
GET
/v2/metadefs/namespaces/​{namespace}​/tags/​{name}​
Get tag definition

Gets a definition for the specified tag.

 

The response body shows a single tag entity.

Normal response codes
200

Request parameters

Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

name plain xsd:string

Name of the tag.

Response parameters

Parameter Style Type Description
name plain xsd:string

Name of the tag.

Example Responses

{
    "created_at": "2015-05-06T23:16:12Z",
    "name": "sample-tag2",
    "updated_at": "2015-05-06T23:16:12Z"
}
PUT
/v2/metadefs/namespaces/​{namespace}​/tags/​{name}​
Update tag definition

Renames a specified tag definition.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
namespace plain xsd:string

The namespace is unique across all users.

name plain xsd:string

Name of the tag.

Response parameters

Parameter Style Type Description
name plain xsd:string

Name of the tag.

Example Requests

{
    "name": "new-tag-name"
}

Example Responses

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

Deletes a specified 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 plain xsd:string

The namespace is unique across all users.

name plain xsd:string

Name of the tag.

This operation does not return a response body.

Metadata definition schemas

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

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

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

 

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

Normal response codes
200

Example Responses

{
    "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
Get metadata definition namespaces schema

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

 

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

Example Responses

{
    "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
Get metadata definition object schema

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

 

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

Normal response codes
200

Example Responses

{
    "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
Get metadata definition objects schema

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

 

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

Example Responses

{
    "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
Get metadata definition property schema

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

 

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

Normal response codes
200

Example Responses

{
    "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
Get metadata definition properties schema

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

 

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

Example Responses

{
    "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
Get metadata definition tag schema

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

 

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

Normal response codes
200

Example Responses

{
    "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
Get metadata definition tags schema

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

 

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

Example Responses

{
    "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
Get metadata definition namespace resource type association schema

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

 

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

Normal response codes
200

Example Responses

{
    "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
Get metadata definition namespace resource type associations schema

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

 

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

Example Responses

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

Creates, lists, and gets details for tasks. (Since API v2.2.)

POST
/v2/tasks
Create tasks

Creates a task.

 
Normal response codes
201

Example Requests

{
    "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
type (Optional) query xsd:string

Filters by a specified task type. A valid value is import, export, or clone.

status (Optional) query xsd:string

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

sort_key (Optional) query xsd:string

Sort key. A valid value is an attribute, such as name, for sorting. Default is created_at.

sort_dir (Optional) query xsd:string

Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc.

Example Responses

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

Shows details for a specified task.

 
Normal response codes
200

Request parameters

Parameter Style Type Description
task_id plain csapi:uuid

The task ID.

Example Responses

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