# variables in header

image_location:

description: |

The image location URL of the image or backup created, HTTP header

"Location: <image location URL>" will be returned.

.. note:: The URL returned may not be accessible to users and should not

be relied upon. Use microversion 2.45 or simply parse the image ID out

of the URL in the Location response header.

in: header

required: true

type: string

max_version: 2.44

server_location:

description: |

The location URL of the server, HTTP header

"Location: <server location URL>" will be returned.

in: header

required: true

type: string

tag_location:

description: |

The location of the tag. It's individual tag URL which can be used for

checking the existence of the tag on the server or deleting the tag from the server.

in: header

required: true

type: string

x-compute-request-id_resp:

description: |

The local request ID, which is a unique ID generated automatically

for tracking each request to nova.

It is associated with the request and appears in the log lines

for that request.

By default, the middleware configuration

ensures that the local request ID appears in the log files.

.. note::

This header exists for backward compatibility.

in: header

required: true

type: string

x-openstack-request-id_req:

description: |

The global request ID, which is a unique common ID

for tracking each request in OpenStack components.

The format of the global request ID must be ``req-`` + UUID (UUID4).

If not in accordance with the format, it is ignored.

It is associated with the request and appears in the log lines

for that request.

By default, the middleware configuration ensures that

the global request ID appears in the log files.

in: header

required: false

type: string

min_version: 2.46

x-openstack-request-id_resp:

description: |

The local request ID, which is a unique ID generated automatically

for tracking each request to nova.

It is associated with the request and appears in the log lines

for that request.

By default, the middleware configuration

ensures that the local request ID appears in the log files.

in: header

required: true

type: string

min_version: 2.46

# variables in path

agent_build_id:

description: |

The id of the agent build.

in: path

required: true

type: string

aggregate_id:

description: |

The aggregate ID.

in: path

required: true

type: integer

api_version:

in: path

required: true

type: string

description: >

The API version as returned in the links from the ``GET /`` call.

before_timestamp:

description: |

Filters the response by the date and time before which to list usage

audits.

The date and time stamp format is as follows:

::

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, ``2015-08-27 09:49:58`` or ``2015-08-27 09:49:58.123456``.

in: path

required: true

type: string

cell_id:

description: |

The UUID of the cell.

in: path

required: true

type: string

console_id:

description: |

The UUID of the console.

in: path

required: true

type: string

console_token:

description: |

Console authentication token.

in: path

required: true

type: string

# Used in the request path for PUT /os-services/disable-log-reason before

# microversion 2.53.

disabled_reason:

description: |

The reason for disabling a service.

in: path

required: false

type: string

domain:

description: |

The registered DNS domain that the DNS drivers publish.

in: path

required: true

type: string

fixed_ip_path:

description: |

The fixed IP of interest to you.

in: path

required: true

type: string

flavor_extra_spec_key:

description: |

The extra spec key for the flavor.

in: path

required: true

type: string

flavor_id:

description: |

The ID of the flavor.

in: path

required: true

type: string

floating_ip_id:

description: |

The ID of the floating IP address.

in: path

required: true

type: string

host_name:

description: |

The name of the host.

in: path

required: true

type: string

hypervisor_hostname_pattern:

description: |

The hypervisor host name or a portion of it.

The hypervisor hosts are selected with the host name matching this pattern.

in: path

required: true

type: string

hypervisor_id:

description: |

The ID of the hypervisor.

in: path

required: true

type: integer

max_version: 2.52

hypervisor_id_uuid:

description: |

The ID of the hypervisor as a UUID.

in: path

required: true

type: string

min_version: 2.53

image_id:

description: |

The UUID of the image.

in: path

required: true

type: string

instance_id:

description: |

The UUID of the instance.

in: path

required: true

type: string

ip:

description: |

The IP address.

in: path

required: true

type: string

key:

description: |

The metadata item key, as a string. Maximum length is 255 characters.

in: path

required: true

type: string

keypair_name_path:

description: |

The keypair name.

in: path

required: true

type: string

migration_id_path:

description: |

The ID of the server migration.

in: path

required: true

type: integer

network_id:

description: |

The UUID of the network.

in: path

required: true

type: string

network_label:

description: |

The network label, such as ``public`` or ``private``.

in: path

required: true

type: string

node_id:

description: |

The node ID.

in: path

required: true

type: string

port_id_path:

description: |

The UUID of the port.

in: path

required: true

type: string

quota_class_id: &quota_class_id

description: |

The ID of the quota class.

Nova supports the ``default`` Quota Class only.

in: path

required: true

type: string

request_id:

description: |

The ID of the request.

in: path

required: true

type: string

security_group_default_rule_id:

description: |

The UUID of the security group rule.

in: path

required: true

type: string

security_group_id:

description: |

The ID of the security group.

in: path

required: true

type: string

security_group_rule_id:

description: |

The ID of the security group rule.

in: path

required: true

type: string

server_group_id:

description: |

The UUID of the server group.

in: path

required: true

type: string

server_id_path:

description: |

The UUID of the server.

in: path

required: true

type: string

service_id_path_2_52:

description: |

The id of the service.

.. note:: This may not uniquely identify a service in a multi-cell

deployment.

in: path

required: true

type: integer

max_version: 2.52

service_id_path_2_53:

description: |

The id of the service as a uuid. This uniquely identifies the service in a

multi-cell deployment.

in: path

required: true

type: string

min_version: 2.53

service_id_path_2_53_no_version:

description: |

The id of the service as a uuid. This uniquely identifies the service in a

multi-cell deployment.

in: path

required: true

type: string

share_id_path:

description: |

The UUID of the attached share.

in: path

required: true

type: string

snapshot_id_path:

description: |

The UUID of the snapshot.

in: path

required: true

type: string

tag:

description: |

The tag as a string.

in: path

required: true

type: string

tenant_id:

description: |

The UUID of the tenant in a multi-tenancy cloud.

in: path

required: true

type: string

volume_id_attached_path:

description: |

The UUID of the attached volume.

in: path

required: true

type: string

volume_id_path:

description: |

The unique ID for a volume.

in: path

required: true

type: string

volume_id_swap_src:

description: |

The UUID of the volume being replaced.

in: path

required: true

type: string

volume_id_to_detach_path:

description: |

The UUID of the volume to detach.

in: path

required: true

type: string

# variables in query

access_ip_v4_query_server:

in: query

required: false

type: string

description: |

Filter server list result by IPv4 address that should be used

to access the server.

access_ip_v6_query_server:

in: query

required: false

type: string

description: |

Filter server list result by IPv6 address that should be used

to access the server.

all_projects:

description: |

Administrator only. Lists server groups for all projects. For example:

``GET /os-server-groups?all_projects=True``

If you specify a tenant ID for a non-administrative user with this query parameter,

the call lists all server groups for the tenant, or project, rather than for

all projects.

Value of this query parameter is not checked, only presence is considered

as request for all projects.

in: query

required: false

type: string

all_tenants:

description: |

Specify the ``all_tenants`` query parameter to ping instances

for all tenants. By default this is only allowed by admin users.

Value of this query parameter is not checked, only presence

is considered as request for all tenants.

in: query

required: false

type: string

all_tenants_query:

description: |

Specify the ``all_tenants`` query parameter to list all instances

for all projects. By default this is only allowed by administrators.

If this parameter is specified without a value, the value defaults to

``True``. If the value is specified, ``1``, ``t``, ``true``,

``on``, ``y`` and ``yes`` are treated as ``True``. ``0``, ``f``,

``false``, ``off``, ``n`` and ``no`` are treated as ``False``.

(They are case-insensitive.)

in: query

required: false

type: boolean

all_tenants_sec_grp_query:

description: |

Specify the ``all_tenants`` query parameter to list all security

groups for all projects. This is only allowed for admin users.

Value of this query parameter is not checked, only presence

is considered as request for all tenants.

in: query

required: false

type: string

availability_zone_query_server:

description: |

Filter the server list result by server availability zone.

This parameter is restricted to administrators until microversion 2.83.

If non-admin users specify this parameter on a microversion less than 2.83,

it will be ignored.

in: query

required: false

type: string

binary_query:

description: |

Filter the service list result by binary name of the service.

in: query

required: false

type: string

changes-since:

description: |

Filters the response by a date and time when the image last changed status.

Use this query parameter to check for changes since a previous request rather

than re-downloading and re-parsing the full status at each polling interval.

If data has changed, the call returns only the items changed since the ``changes-since``

time. If data has not changed since the ``changes-since`` time, the call returns an

empty list.

To enable you to keep track of changes, this filter also displays images

that were deleted if the ``changes-since`` value specifies a date in the last 30 days.

Items deleted more than 30 days ago might be returned, but it is not guaranteed.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

in: query

required: false

type: string

changes_before_instance_action:

description: |

Filters the response by a date and time stamp when the instance actions last changed.

Those instances that changed before or equal to the specified date and time stamp

are returned.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-before`` must be later than or equal to

the value of the ``changes-since`` otherwise API will return 400.

in: query

required: false

type: string

min_version: 2.66

changes_before_migration:

description: |

Filters the response by a date and time stamp when the migration last

changed. Those migrations that changed before or equal to the specified date and time

stamp are returned.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-before`` must be later than or equal to

the value of the ``changes-since`` otherwise API will return 400.

in: query

required: false

type: string

min_version: 2.66

changes_before_server:

description: |

Filters the response by a date and time stamp when the server last changed.

Those servers that changed before or equal to the specified date and time stamp

are returned. To help keep track of changes this may also return recently deleted

servers.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-before`` must be later than or equal to

the value of the ``changes-since`` otherwise API will return 400.

in: query

required: false

type: string

min_version: 2.66

changes_since_instance_action:

description: |

Filters the response by a date and time stamp when the instance action last

changed.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-since`` must be earlier than or equal to

the value of the ``changes-before`` otherwise API will return 400.

in: query

required: false

type: string

min_version: 2.58

changes_since_migration:

description: |

Filters the response by a date and time stamp when the migration last

changed. Those changed after the specified date and time stamp are returned.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-since`` must be earlier than or equal to

the value of the ``changes-before`` otherwise API will return 400.

in: query

required: false

type: string

min_version: 2.59

changes_since_server:

description: |

Filters the response by a date and time stamp when the server last

changed status. To help keep track of changes this may also return

recently deleted servers.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

When both ``changes-since`` and ``changes-before`` are specified,

the value of the ``changes-since`` must be earlier than or equal to

the value of the ``changes-before`` otherwise API will return 400.

in: query

required: false

type: string

config_drive_query_server:

description: |

Filter the server list result by the config drive setting of the server.

This parameter is restricted to administrators until microversion 2.83.

If non-admin users specify this parameter on a microversion less than 2.83,

it will be ignored.

in: query

required: false

type: string

created_at_query_server:

description: |

Filter the server list result by a date and time stamp when server was created.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

This parameter is restricted to administrators until microversion 2.83.

If non-admin users specify this parameter on a microversion less than 2.83,

it will be ignored.

in: query

required: false

type: string

delete_info:

description: |

Information for snapshot deletion. Include the ID of the associated volume. For

example:

.. code-block:: javascript

DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'

in: query

required: true

type: string

deleted_query:

in: query

required: false

type: boolean

description: |

Show deleted items only. In some circumstances deleted items will still

be accessible via the backend database, however there is no

contract on how long, so this parameter should be used with

caution. ``1``, ``t``, ``true``, ``on``, ``y`` and ``yes`` are treated as

``True`` (case-insensitive). Other than them are treated as ``False``.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

description_query_server:

description: |

Filter the server list result by description.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

.. note::

``display_description`` can also be requested which is alias of

``description`` but that is not recommended to use as that will

be removed in future.

in: query

required: false

type: string

detailed_simple_tenant_usage:

description: |

Specify the ``detailed=1`` query parameter to get detail information

('server_usages' information).

in: query

required: false

type: integer

disk_config_query_server:

description: |

Filter the server list result by the ``disk_config`` setting of the server,

Valid values are:

- ``AUTO``

- ``MANUAL``

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

in: query

required: false

type: string

end_simple_tenant_usage:

description: |

The ending time to calculate usage statistics on compute and

storage resources. The date and time stamp format is any of

the following ones:

::

CCYY-MM-DDThh:mm:ss

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

::

CCYY-MM-DDThh:mm:ss.NNNNNN

For example, ``2015-08-27T09:49:58.123456``.

::

CCYY-MM-DD hh:mm:ss.NNNNNN

For example, ``2015-08-27 09:49:58.123456``.

If you omit this parameter, the current time is used.

in: query

required: false

type: string

exclude:

description: |

Specify ``exclude=uuid[,uuid...]`` to exclude the instances from the results.

in: query

required: false

type: string

flavor_is_public_query:

in: query

required: false

type: string

description: |

This parameter is only applicable to users with the administrative role.

For all other non-admin users, the parameter is ignored and only public

flavors will be returned. Filters the flavor list based on whether the

flavor is public or private. If the value of this parameter is not

specified, it is treated as ``True``. If the value is specified, ``1``,

``t``, ``true``, ``on``, ``y`` and ``yes`` are treated as ``True``. ``0``,

``f``, ``false``, ``off``, ``n`` and ``no`` are treated as ``False``

(they are case-insensitive). If the value is ``None`` (case-insensitive)

both public and private flavors will be listed in a single request.

flavor_name_query:

description: |

Filters the response by a flavor name, as a string. You can use regular expressions

in the query. For example, the ``?name=bob`` regular expression returns both bob

and bobb. If you must match on only bob, you can use a regular expression that

matches the syntax of the underlying database server that is implemented for Compute,

such as MySQL or PostgreSQL.

format: regexp

in: query

required: false

type: string

min_version: 2.102

flavor_query:

description: |

Filters the response by a flavor, as a UUID. A flavor is a combination of memory,

disk size, and CPUs.

in: query

required: false

type: string

host_query_server:

description: |

Filter the server list result by the host name of compute node.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

in: query

required: false

type: string

host_query_service:

description: |

Filter the service list result by the host name.

in: query

required: false

type: string

hostname_query_server:

description: |

Filter the server list result by the host name of server.

This parameter is only valid when specified by administrators until

microversion 2.90, after which it can be specified by all users.

If non-admin users specify this parameter before microversion 2.90, it is

ignored.

in: query

required: false

type: string

hypervisor_hostname_pattern_query:

description: |

The hypervisor host name or a portion of it. The hypervisor hosts are

selected with the host name matching this pattern.

.. note:: ``limit`` and ``marker`` query parameters for paging are

not supported when listing hypervisors using a hostname pattern.

Also, ``links`` will not be returned in the response when using this

query parameter.

in: query

required: false

type: string

min_version: 2.53

hypervisor_limit:

description: |

Requests a page size of items. Returns a number of items up to a limit value.

Use the ``limit`` parameter to make an initial limited request and use the ID

of the last-seen item from the response as the ``marker`` parameter value in a

subsequent limited request.

in: query

required: false

type: integer

min_version: 2.33

hypervisor_marker:

description: |

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.

in: query

required: false

type: integer

min_version: 2.33

max_version: 2.52

hypervisor_marker_uuid:

description: |

The ID of the last-seen item as a UUID. 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.

in: query

required: false

type: string

min_version: 2.53

hypervisor_query:

description: |

Filters the response by a hypervisor type.

in: query

required: false

type: string

hypervisor_with_servers_query:

description: |

Include all servers which belong to each hypervisor in the response output.

in: query

required: false

type: boolean

min_version: 2.53

image_name_query:

description: |

Filters the response by an image name, as a string.

in: query

required: false

type: string

image_query:

description: |

Filters the response by an image, as a UUID.

.. note::

'image_ref' can also be requested which is alias of 'image'

but that is not recommended to use as that will be removed in future.

in: query

required: false

type: string

image_server_query:

description: |

Filters the response by a server, as a URL.

format: uri

in: query

required: false

type: string

image_status_query:

description: |

Filters the response by an image status, as a string. For example, ``ACTIVE``.

in: query

required: false

type: string

image_type_query:

description: |

Filters the response by an image type. For example, ``snapshot`` or ``backup``.

in: query

required: false

type: string

include:

description: |

Specify ``include=uuid[,uuid...]`` to include the instances in the results.

in: query

required: false

type: string

instance_action_limit:

description: |

Requests a page size of items. Returns a number of items up to a limit value.

Use the ``limit`` parameter to make an initial limited request and use the

last-seen item from the response as the ``marker`` parameter value in a

subsequent limited request.

in: query

required: false

type: integer

min_version: 2.58

instance_action_marker:

description: |

The ``request_id`` of the last-seen instance action. Use the ``limit``

parameter to make an initial limited request and use the last-seen

item from the response as the ``marker`` parameter value in a subsequent

limited request.

in: query

required: false

type: string

min_version: 2.58

ip6_query:

description: |

An IPv6 address to filter results by.

Up to microversion 2.4, this parameter is only valid when specified

by administrators. If non-admin users specify this parameter,

it is ignored.

Starting from microversion 2.5, this parameter is valid for no-admin users

as well as administrators.

in: query

required: false

type: string

ip_query:

description: |

An IPv4 address to filter results by.

in: query

required: false

type: string

kernel_id_query_server:

in: query

required: false

type: string

description: |

Filter the server list result by the UUID of the kernel image

when using an AMI.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

key_name_query_server:

description: |

Filter the server list result by keypair name.

This parameter is restricted to administrators until microversion 2.83.

If non-admin users specify this parameter on a microversion less than 2.83,

it will be ignored.

in: query

required: false

type: string

keypair_limit:

description: |

Requests a page size of items. Returns a number of items up to a limit value.

Use the ``limit`` parameter to make an initial limited request and use the

last-seen item from the response as the ``marker`` parameter value in a

subsequent limited request.

in: query

required: false

type: integer

min_version: 2.35

keypair_marker:

description: |

The last-seen item. Use the ``limit`` parameter to make an initial limited

request and use the last-seen item from the response as the ``marker``

parameter value in a subsequent limited request.

in: query

required: false

type: string

min_version: 2.35

keypair_user:

in: query

required: false

type: string

description: |

This allows administrative users to operate key-pairs of specified

user ID.

min_version: 2.10

launch_index_query_server:

description: |

Filter the server list result by the sequence in which the

servers were launched.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

in: query

required: false

type: integer

launched_at_query_server:

description: |

Filter the server list result by a date and time stamp when the instance was launched.

The date and time stamp format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:

::

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

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

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

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

This parameter is restricted to administrators until microversion 2.83.

If non-admin users specify this parameter on a microversion less than 2.83,

it will be ignored.

in: query

required: false

type: string

limit:

description: |

Requests a page size of items. Returns a number of items up to a limit value.

Use the ``limit`` parameter to make an initial limited request and use the ID

of the last-seen item from the response as the ``marker`` parameter value in a

subsequent limited request.

in: query

required: false

type: integer

limit_simple:

description: |

Used in conjunction with ``offset`` to return a slice of items. ``limit``

is the maximum number of items to return. If ``limit`` is not specified,

or exceeds the configurable ``max_limit``, then ``max_limit`` will be

used instead.

in: query

required: false

type: integer

locked_by_query_server:

description: |

Filter the server list result by who locked the server, possible value

could be ``admin`` or ``owner``.

This parameter is only valid when specified by administrators.

If non-admin users specify this parameter, it is ignored.

in: query