# V2 Web API

## Capabilities

The Capabilities API allows you to directly discover which functions from the V2 API functionality, including the selectable aggregate functions, are supported by the currently configured storage driver. A capabilities query returns a flattened dictionary of properties with associated boolean values - a ‘False’ or absent value means that the corresponding feature is not available in the backend.

GET /v2/capabilities

  Returns a flattened dictionary of API capabilities.

  Capabilities supported by the currently configured storage driver.

  Return type:

    `Capabilities`

## Alarms

GET /v2/alarms

  Return all alarms, based on the query provided.

  Parameters:

    - q (list(`Query`)) – Filter rules for the alarms to be returned.

    - sort (list(`str`)) – A list of pairs of sort key and sort dir.

    - limit (`int`) – The maximum number of items to be return.

    - marker (`str`) – The pagination query marker.

  Return type:

    list(`Alarm`)

POST /v2/alarms

  Create a new alarm.

  Parameters:

    - data (`Alarm`) – an alarm within the request body.

  Return type:

    `Alarm`

GET /v2/alarms/(alarm_id)

  Return this alarm.

  Return type:

    `Alarm`

PUT /v2/alarms/(alarm_id)

  Modify this alarm.

  Parameters:

    - data (`Alarm`) – an alarm within the request body.

  Return type:

    `Alarm`

DELETE /v2/alarms/(alarm_id)

  Delete this alarm.

GET /v2/alarms/(alarm_id)/history

  Assembles the alarm history requested.

  Parameters:

    - q (list(`Query`)) – Filter rules for the changes to be described.

    - sort (list(`str`)) – A list of pairs of sort key and sort dir.

    - limit (`int`) – The maximum number of items to be return.

    - marker (`str`) – The pagination query marker.

  Return type:

    list(`AlarmChange`)

PUT /v2/alarms/(alarm_id)/state

  Set the state of this alarm.

  Parameters:

    - state (`Enum(ok, alarm, insufficient data)`) – an alarm state within the request body.

  Return type:

    `Enum(ok, alarm, insufficient data)`

GET /v2/alarms/(alarm_id)/state

  Get the state of this alarm.

  Return type:

    `Enum(ok, alarm, insufficient data)`

## Filtering Queries

The filter expressions of the query feature operate on the fields of Alarm and AlarmChange. The following comparison operators are supported: =, !=, <, <=, >, >= and in; and the following logical operators can be used: and or and not. The field names are validated against the database models.

Complex Query supports defining the list of orderby expressions in the form of [{“field_name”: “asc”}, {“field_name2”: “desc”}, …].

The number of the returned items can be bounded using the limit option.

The filter, orderby and limit are all optional fields in a query.

POST /v2/query/alarms

  Define query for retrieving Alarm data.

  Parameters:

    - body (`ComplexQuery`) – Query rules for the alarms to be returned.

  Return type:

    list(`Alarm`)

POST /v2/query/alarms/history

  Define query for retrieving AlarmChange data.

  Parameters:

    - body (`ComplexQuery`) – Query rules for the alarm history to be returned.

  Return type:

    list(`AlarmChange`)

## Composite rule Alarm

The composite type alarm allows users to specify a composite rule to define an alarm with multiple triggering conditions, using a combination of and and or relations. A composite rule is composed of multiple threshold rules or gnocchi rules. A sample composite alarm request form is as follows:

    {
        "name": "test_composite",
        "type": "composite",
        "composite_rule": {
            "and": [THRESHOLD_RULE1, THRESHOLD_RULE2, {
                'or': [THRESHOLD_RULE3, GNOCCHI_RULE1,
                       GNOCCHI_RULE2, GNOCCHI_RULE3]
            }]
        }
    }

A sub-rule in composite_rule is same as a threshold_rule in threshold alarm or a gnocchi_rule in gnocchi alarm. Additionally it has a mandatory type field to specify the rule type, like in the following sample:

    {
        "threshold": 0.8,
        "meters": [
            "f6857d3f-bde6-441a-aa1d-e98fa4ea543f",
            "ea1491ca-5309-4b5a-9f05-34409c6e8b6c"
        ],
        "type": "gnocchi_resources_threshold"
    }

this page last updated: 2026-04-01 16:27:05

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug