API | Deckhouse modules

The module lifecycle stage: General Availability

Authentication

Endpoints requiring authentication must be called with the X-Auth-Token HTTP request header containing an API token.

Metrics

Sending metrics

The following protocol is supported for sending metrics: Prometheus Remote-Write.

Example request:

POST /api/v1/push

This endpoint accepts an HTTP POST request. The request data is encoded using Protocol Buffers and compressed with Snappy. The protobuf message definition can be found in the pkg/mimirpb/mimir.proto file. The HTTP request must contain the X-Prometheus-Remote-Write-Version header with version 0.1.0.

Authentication required…

Viewing metrics

General format

Instant queries for metrics

This endpoint evaluates an instant query at a single point in time.

Example request:

GET /prometheus/api/v1/query

POST /prometheus/api/v1/query

Authentication required…

URL query parameters:

query=<string>: Prometheus expression query string.
time=<rfc3339 | unix_timestamp>: evaluation timestamp. Optional.
timeout=<duration>: evaluation timeout. Optional. Defaults to the value of the -query.timeout flag.

If the time parameter is omitted, the current server time is used.

You can URL-encode the query parameters directly in the request body using the POST method and the Content-Type: application/x-www-form-urlencoded header. This is useful when specifying large queries that may exceed the URL length limit.

Format of the data section in the query result:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> refers to the query result data, the format of which depends on resultType. See expression query result formats.

Example:

Example request evaluating the expression up at the time 2015-07-01T20:10:51.781Z:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/prometheus/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

Response:

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Range queries

This endpoint evaluates an expression query over a range of time:

GET /prometheus/api/v1/query_range POST /prometheus/api/v1/query_range

Authentication required.

URL parameters:

query=<string>: Prometheus expression string.
start=<rfc3339 | unix_timestamp>: start timestamp.
end=<rfc3339 | unix_timestamp>: end timestamp.
step=<duration | float>: query resolution step width (duration format or number of seconds as a float).
timeout=<duration>: evaluation timeout. Optional.

Example:

Example request with the expression up over a 30-second range with 15-second resolution:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/prometheus/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'

Response:

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

Querying metadata

Deckhouse Observability Platform provides several APIs for querying metadata about time series and their labels.

Finding series by label set

This endpoint returns a list of time series matching a certain label set:

GET /prometheus/api/v1/series POST /prometheus/api/v1/series

Authentication required…

URL parameters:

match[]=<series_selector>: repeated argument for the series selector that selects the returned series. At least one match[] argument must be provided.
start=<rfc3339 | unix_timestamp>: start timestamp.
end=<rfc3339 | unix_timestamp>: end timestamp.
limit=<number>: maximum number of returned series. Default is 0, meaning no limit.

Example:

$ curl -H "X-Auth-Token: <API-token>" \
    -g 'https://api.dop.example.com/prometheus/api/v1/series?' \
    --data-urlencode 'match[]=up' \
    --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'

Response:

{
   "status" : "success",
   "data" : [
      { "__name__" : "up", "job" : "prometheus", "instance" : "localhost:9090" },
      { "__name__" : "up", "job" : "node", "instance" : "localhost:9091" },
      { "__name__" : "process_start_time_seconds", "job" : "prometheus", "instance" : "localhost:9090" }
   ]
}

Getting label names

This endpoint returns a list of label names:

GET /prometheus/api/v1/labels POST /prometheus/api/v1/labels

Authentication required…

Example:

$ curl -H "X-Auth-Token: <API-token>" \
    'https://api.dop.example.com/prometheus/api/v1/labels'

Response:

{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

Getting label values

This endpoint returns a list of values for the specified label name:

GET /prometheus/api/v1/label/<label_name>/values

Authentication required…

Example:

Example request for values of the job label:

$ curl -H "X-Auth-Token: <API-token>" \
    https://api.dop.example.com/prometheus/api/v1/label/job/values

Response:

{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}

Expression query result formats

Expression queries may return the following values in the result property of the data section. The <sample_value> placeholders are used to represent numeric values. Since JSON does not support special floating-point values such as NaN, Inf, and -Inf, sample data is transferred as quoted string values instead of numbers.

The "histogram" and "histograms" keys only appear if the response contains experimental native histograms. The <histogram> placeholder is explained in a separate section below.

Range vectors

Range vectors are returned as result type matrix. The corresponding result property has the following format:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ],
    "histograms": [ [ <unix_time>, <histogram> ], ... ]
  },
  ...
]

Each series may include a values key, a histograms key, or both. For each timestamp there will be only one sample — either of type float or of type histogram.

Series are returned sorted by metrics. Functions such as sort and sort_by_label do not affect range vectors.

Instant vectors

Instant vectors are returned as result type vector. The corresponding result property has the following format:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ],
    "histogram": [ <unix_time>, <histogram> ]
  },
  ...
]

Each series may contain a value key or a histogram key, but not both.

Series are not guaranteed to be in any particular order unless a function such as sort or sort_by_label was used.

Scalars

Scalar results are returned as result type scalar. The corresponding result property has the following format:

[ <unix_time>, "<scalar_value>" ]

Strings

String results are returned as result type string. The corresponding result property has the following format:

[ <unix_time>, "<string_value>" ]

Logs

Sending logs

POST /loki/api/v1/push

Authentication required…

This endpoint is used to send logs to Deckhouse Observability Platform. By default, the POST body should be Snappy-compressed Protocol Buffer message:

These POST requests require the Content-Type: application/x-protobuf HTTP header.

Alternatively, if the Content-Type header is set to application/json, you can send the POST body in JSON format:

{
  "streams": [
    {
      "stream": {
        "label": "value"
      },
      "values": [
          [ "<Unix Timestamp in nanoseconds>", "<log line>" ],
          [ "<Unix Timestamp in nanoseconds>", "<log line>" ]
      ]
    }
  ]
}

You can set the Content-Encoding: gzip request header to send compressed JSON.

You can also attach structured metadata to each log line by adding a JSON object at the end of the log array. This object must not contain nested objects, and must contain only string keys and values. It must be specified immediately after the log line:

Example:

"values": [
    [ "<Unix Timestamp in nanoseconds>", "<log line>", {"trace_id": "0242ac120002", "user_id": "superUser123"}]
]

Examples:

Example cURL command to send a stream with the label foo=bar2 and a single log line "fizzbuzz" using JSON encoding:

curl -H "Content-Type: application/json" \
  -H "X-Auth-Token: <API-token>" \
  -s -X POST "https://api.dop.example.com/loki/api/v1/push" \
  --data-raw '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}'

Viewing logs

Instant queries for logs

GET /loki/api/v1/query

Authentication required…

This endpoint allows you to execute log queries for a specific point in time. Instant queries are used only for querying logs with LogQL metric queries and will return a 400 (Bad Request) error when used with log queries.

URL query parameters:

query: LogQL query. Queries with invalid LogQL syntax will return an error.
limit: Maximum number of entries to return. Default is 100. Only applies to queries that return log lines.
time: Query evaluation time as a Unix Timestamp in nanoseconds (or another format). Default is the current time.
direction: Determines the sort order of logs. Supported values: forward or backward. Default is backward.

Response format:

{
  "status": "success",
  "data": {
    "resultType": "vector" | "streams",
    "result": [<vector value>] | [<stream value>],
    "stats": [<statistics>]
  }
}

Where vector value has the format:

{
  "metric": {
    <label key-value pairs>
  },
  "value": [
    <number: second Unix Timestamp>,
    <string: value>
  ]
}

and stream value has the format:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond Unix Timestamp>,
      <string: log line>
    ],
    ...
  ]
}

Entries in the values array are sorted by timestamp. The most recent entry is first when using direction=backward. The oldest entry is first when using direction=forward.

Example:

curl -G -s -H 'X-Auth-Token: <API-token>'  "https://api.dop.example.com/loki/api/v1/query" \
  --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq

Response:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {},
        "value": [
          1588889221,
          "1267.1266666666666"
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "value": [
          1588889221,
          "37.77166666666667"
        ]
      },
      {
        "metric": {
          "level": "info"
        },
        "value": [
          1588889221,
          "37.69"
        ]
      }
    ],
    "stats": {
      ...
    }
  }
}

Range query

GET /loki/api/v1/query_range

Authentication required…

This endpoint allows you to query logs within a specific time range. It applies to both log queries and LogQL metric queries.

URL query parameters:

query: LogQL query to execute.
limit: Maximum number of entries to return. Default is 100. Only applies to query types that return a stream (log lines).
start: Start time of the query as a Unix Timestamp in nanoseconds or another supported format. Default is one hour ago. Loki returns results with a timestamp greater than or equal to this value.
end: End time of the query, also as a Unix Timestamp in nanoseconds or another supported format. Default is the current time. Loki returns results with a timestamp less than this value.
since: Duration used to calculate the start relative to the end. If the end value is in the future, the start time is calculated as this duration before the current moment. Any specified value of the start parameter takes precedence over since.
step: Query resolution step in duration format or a floating-point number representing seconds. Duration implies Prometheus-format strings such as [0-9]+[smhdwy]. For example, 5m means a duration of 5 minutes. Default is a dynamic value based on start and end. Applies to queries that return a matrix response.
interval: Returns entries at no less than the specified interval, which can be set as a duration or a floating-point number of seconds. Works only for queries returning a stream. Not to be confused with the step parameter, see explanation below.
direction: Determines the sort order of logs. Supported values are forward (ascending) or backward (descending). Default is backward.

Response format:

{
  "status": "success",
  "data": {
    "resultType": "matrix" | "streams",
    "result": [<matrix value>] | [<stream value>],
    "stats" : [<statistics>]
  }
}

Where <matrix value> has the format:

{
  "metric": {
    <label key-value pairs>
  },
  "values": [
    [
      <number: second Unix Timestamp>,
      <string: value>
    ],
    ...
  ]
}

and <stream value> has the format:

{
  "stream": {
    <label key-value pairs>
  },
  "values": [
    [
      <string: nanosecond Unix Timestamp>,
      <string: log line>
    ],
    ...
  ]
}

Entries in the values array are sorted by timestamp: when using direction=backward, the most recent entry comes first; when using forward, the oldest entry comes first.

Examples:

curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query_range" \
  --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \
  --data-urlencode 'step=300' | jq

Response:

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
       "metric": {
          "level": "info"
        },
        "values": [
          [
            1588889221,
            "137.95"
          ],
          [
            1588889221,
            "467.115"
          ],
          [
            1588889221,
            "658.8516666666667"
          ]
        ]
      },
      {
        "metric": {
          "level": "warn"
        },
        "values": [
          [
            1588889221,
            "137.27833333333334"
          ],
          [
            1588889221,
            "467.69"
          ],
          [
            1588889221,
            "660.6933333333334"
          ]
        ]
      }
    ],
    "stats": {
      ...
    }
  }
}

Query labels

GET /loki/api/v1/labels

Authentication required…

This endpoint returns a list of known labels within a time range.

URL query parameters:

start: Start time of the query as a Unix Timestamp in nanoseconds. Default is 6 hours ago.
end: End time, also as a Unix Timestamp in nanoseconds. Default is the current time.
since: Duration used to calculate the start relative to the end.
query: Log stream selector that selects the streams for which to display labels. Example: {app="myapp", environment="dev"}

Response format:

{
  "status": "success",
  "data": [
    <label string>,
    ...
  ]
}

Example:

curl -G -s -H"X-Auth-Token: <API-token>"  "https://api.dop.example.com/loki/api/v1/labels" | jq

Response:

{
  "status": "success",
  "data": [
    "foo",
    "bar",
    "baz"
  ]
}

Query label values

GET /loki/api/v1/label/<name>/values

Authentication required…

This endpoint returns a list of possible values for the label <name> within a time range.

URL query parameters:

start: Start time.
end: End time.
since: Duration used to calculate the start relative to the end.
query: Log selector for selecting streams and returning label values.

Example:

curl -G -s -H"X-Auth-Token: <API-token>"  "https://api.dop.example.com/loki/api/v1/label/foo/values" | jq

Response:

{
  "status": "success",
  "data": [
    "cat",
    "dog",
    "axolotl"
  ]
}

Traces

Sending traces

Deckhouse Observability Platform supports receiving traces via several protocols.

Authentication required… (permission Traces: write).

OTLP HTTP

POST /otlp/v1/traces

POST /v1/traces

Send traces using the OpenTelemetry (OTLP) protocol over HTTP. The request body must contain data in OTLP JSON or OTLP Protobuf format.

Example:

curl -X POST "https://api.dop.example.com/otlp/v1/traces" \
  -H "X-Auth-Token: <API-token>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "resourceSpans": [{
      "resource": {
        "attributes": [{"key": "service.name", "value": {"stringValue": "my-service"}}]
      },
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "example-span",
          "kind": 1,
          "startTimeUnixNano": "1544712660000000000",
          "endTimeUnixNano": "1544712661000000000",
          "attributes": [{"key": "http.method", "value": {"stringValue": "GET"}}],
          "status": {}
        }]
      }]
    }]
  }'

OTLP gRPC

opentelemetry.proto.collector.trace.v1.TraceService/Export

Send traces using the OpenTelemetry (OTLP) protocol over gRPC.

Example:

grpcurl -H "X-Auth-Token: <API-token>" \
  -d '{"resourceSpans": [...]}' \
  api.dop.example.com:443 \
  opentelemetry.proto.collector.trace.v1.TraceService/Export

Jaeger Thrift HTTP

POST /jaeger/api/traces

Send traces using the Jaeger Thrift protocol over HTTP.

Zipkin

POST /zipkin/spans

Send traces using the Zipkin protocol.

Viewing traces

Authentication required… (permission Traces: read).

Getting a trace by identifier

GET /tempo/api/traces/{traceID}

GET /tempo/api/v2/traces/{traceID}

Returns a trace by its identifier. The v2 version returns the result in OTLP format.

Example:

curl -H "X-Auth-Token: <API-token>" \
  "https://api.dop.example.com/tempo/api/traces/5b8efff798038103d269b633813fc60c"

Searching traces

GET /tempo/api/search

GET /tempo/api/v2/search

Searches for traces based on specified parameters.

URL query parameters:

q=<string>: TraceQL query string. Optional.
tags=<string>: filter by tags in key=value format. Optional.
minDuration=<duration>: minimum trace duration (e.g., 1s, 100ms). Optional.
maxDuration=<duration>: maximum trace duration. Optional.
limit=<int>: maximum number of results. Optional.
start=<int>: start time (in seconds since Unix epoch). Optional.
end=<int>: end time (in seconds since Unix epoch). Optional.

Example:

curl -H "X-Auth-Token: <API-token>" \
  "https://api.dop.example.com/tempo/api/search?q=%7Bspan.http.status_code+%3E%3D+400%7D&limit=20"

Build information

GET /tempo/api/status/buildinfo

Returns version and build information for the Tempo component.

Example:

curl -H "X-Auth-Token: <API-token>" \
  "https://api.dop.example.com/tempo/api/status/buildinfo"

Triggers

Trigger parameters

metadata.name: trigger name, must be unique (not used by another project trigger or global trigger), lowercase Latin letters and - are allowed
metadata.generation: trigger version
metadata.resourceVersion: global trigger version
metadata.creationTimestamp: trigger creation date/time
metadata.annotations: list of trigger annotations in name-value format. Currently the trigger category annotation metadata.deckhouse.io/category is supported
spec.alertMetadata.annotations: arbitrary list of trigger annotations in name-value format.
spec.alertMetadata.additionalLabels: arbitrary list of trigger labels in name-value format.
spec.delays.firing: delay before trigger fires (1s, 1m, etc.)
spec.delays.resolving: duration of firing after resolution (1s, 1m, etc.)
spec.expression: trigger expression, must be a valid Prometheus expression.
spec.thresholds: array of firing thresholds, at least one is required.
- valueExpression: threshold value or expression
- operator: operator, allowed values: Equal | GreaterThan | LessThan | LessThanOrEqual | GreaterThanOrEqual | NotEqual
- severity: severity level, allowed values: Critical | Info | Warning | Setup

Getting the list of project triggers

This endpoint returns the list of project triggers (not including global triggers).

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "List",
    "metadata":
    {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityMetricsAlertingRule",
            "metadata":
            {
                "creationTimestamp": "2024-12-11T10:38:23Z",
                "generation": 1,
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Main"
                },
                "name": "rule-name",
                "resourceVersion": 1
            },
            "spec":
            {
                "alertMetadata":
                {
                    "annotations":
                    {
                        "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
                    },
                    "additionalLabels":
                    {
                        "additional_label": "value"
                    }
                },
                "delays":
                {
                    "firing": "1m",
                    "resolving": "0s"
                },
                "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
                "thresholds":
                [
                    {
                        "valueExpression": "0.5",
                        "operator": "GreaterThan",
                        "severity": "Warning"
                    }
                ]
            }
        }
    ]
}

Getting a trigger

This endpoint returns a trigger by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: trigger name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-11T10:42:56Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "Main"
        },
        "name": "test1",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1m",
            "resolving": "0s"
        },
        "expression": "job:request_latency_seconds:mean5m{job=\"myjob\"}",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Warning"
            }
        ]
    }
}

Creating a trigger

This endpoint creates a new trigger.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/' -d \
'
{
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "some-name"
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "some description summary"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1s",
            "resolving": "1s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "critical"
            }
        ]
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-11T10:48:11Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "some-name",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "some description summary"
            },
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "delays":
        {
            "firing": "1s",
            "resolving": "1s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Critical"
            }
        ]
    }
}

Updating a trigger

This endpoint updates an existing trigger.

PUT api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: trigger name

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name' -d \
'
{
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        }
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "somelabel": "value"
            }
        },
        "delays":
        {
            "firing": "2s",
            "resolving": "3s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "critical"
            }
        ]
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsAlertingRule",
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:16:03Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "critical"
        },
        "name": "test1",
        "resourceVersion": 1
    },
    "spec":
    {
        "alertMetadata":
        {
            "annotations":
            {
                "summary": "{{ $labels.instance }} pgbouncer '{{ $labels.conf }}' configuration incomplete"
            },
            "additionalLabels":
            {
                "somelabel": "value"
            }
        },
        "delays":
        {
            "firing": "2s",
            "resolving": "3s"
        },
        "expression": "vector(10)",
        "thresholds":
        [
            {
                "valueExpression": "0.5",
                "operator": "GreaterThan",
                "severity": "Critical"
            }
        ]
    }
}

Deleting a trigger

This endpoint deletes an existing trigger.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: trigger name

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/alertingrules/:name'

Errors when creating or updating triggers

If the request to create or update a trigger contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Name has already been taken"}

Recording Rules

Recording rule parameters

metadata.name: metric name, must be unique (not used by another project metric or global metric), lowercase Latin letters and - are allowed
metadata.generation: metric version
metadata.resourceVersion: global metric version
metadata.creationTimestamp: metric creation date/time
metadata.annotations: list of metric annotations in name-value format. Currently the metric category annotation metadata.deckhouse.io/category is supported
spec.expression: metric expression, must be a valid Prometheus expression.
spec.alertMetadata.targetMetric: metric parameters
- name: metric name, lowercase Latin letters and : are allowed, example: some:metric, must be unique.
- additionalLabels: arbitrary list of metric labels in name-value format.

Getting the list of project recording rules

This endpoint returns the list of project recording rules (not including global metrics).

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules'

Example response:

{
    "apiVersion": "v1",
    "kind": "List",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityMetricsRecordingRule",
            "spec":
            {
                "expression": "vector(10)",
                "targetMetric":
                {
                    "name": "test:vector",
                    "additionalLabels":
                    {
                        "test": "test",
                        "author": "test"
                    }
                }
            },
            "metadata":
            {
                "creationTimestamp": "2024-12-13T06:24:30Z",
                "generation": 1,
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Main"
                },
                "name": "test-vector-1",
                "resourceVersion": 1
            }
        }
    ]
}

Getting a recording rule

This endpoint returns a recording rule by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: recording rule name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(10)",
        "targetMetric":
        {
            "name": "test:vector",
            "additionalLabels":
            {
                "test": "test",
                "author": "test"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:37:39Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "Main"
        },
        "name": "test-vector-1",
        "resourceVersion": 1
    }
}

Creating a recording rule

This endpoint creates a new recording rule.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules' -d \
'
{
    "kind": "ObservabilityMetricsRecordingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording"
        },
        "name": "some-name"
    },
    "spec":
    {
        "targetMetric":
        {
            "name": "metric:rule:name",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "expression": "vector(10)"
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(10)",
        "targetMetric":
        {
            "name": "metric:rule:name",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:40:08Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording"
        },
        "name": "some-name",
        "resourceVersion": 1
    }
}

Updating a recording rule

This endpoint updates an existing recording rule.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: recording rule name

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name' -d \
'
{
    "kind": "ObservabilityMetricsRecordingRule",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording updated"
        },
        "name": "test-vector-1"
    },
    "spec":
    {
        "targetMetric":
        {
            "name": "metric:rule:name:updated",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        },
        "expression": "vector(11)"
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityMetricsRecordingRule",
    "spec":
    {
        "expression": "vector(11)",
        "targetMetric":
        {
            "name": "metric:rule:name:updated",
            "additionalLabels":
            {
                "testlabel": "value"
            }
        }
    },
    "metadata":
    {
        "creationTimestamp": "2024-12-13T06:42:35Z",
        "generation": 1,
        "annotations":
        {
            "metadata.deckhouse.io/category": "recording updated"
        },
        "name": "test-vector-1",
        "resourceVersion": 1
    }
}

Deleting a recording rule

This endpoint deletes an existing metric.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: metric name

Authentication required… The token must have “API management” and “Triggers and recording rules” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/recordingrules/:name'

Errors when creating or updating metrics

If the request to create or update a metric contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Name has already been taken"}

Dashboards

Dashboard parameters

metadata.name: dashboard name, must be unique (not used by another project dashboard or global dashboard), lowercase Latin letters and - are allowed
metadata.generation: dashboard version
metadata.resourceVersion: global dashboard version
metadata.creationTimestamp: dashboard creation date/time
metadata.annotations: list of dashboard annotations in name-value format. Currently the following annotations are supported:
- metadata.deckhouse.io/category - dashboard category
- metadata.deckhouse.io/title - display title
spec.definition: JSON dashboard definition

Getting the list of project dashboards

This endpoint returns the list of project dashboards (not including global dashboards).

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Dashboards” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboardList",
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityDashboard",
            "metadata":
            {
                "annotations":
                {
                    "metadata.deckhouse.io/category": "Category-3",
                    "metadata.deckhouse.io/title": "dashboard-3"
                },
                "creationTimestamp": "2025-01-24T10:32:23Z",
                "generation": 1,
                "name": "dash-dash-board-3",
                "namespace": "spicy-space-1",
                "resourceVersion": 1
            },
            "spec":
            {
                "definition": "{\"id\":255,\"uid\":\"GrxobkC5leWtZmaE\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-3\"}"
            }
        }
    ]
}

Getting a dashboard

This endpoint returns a dashboard by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: dashboard name. Required

Authentication required… The token must have “API management” and “Dashboards” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "Category-1",
            "metadata.deckhouse.io/title": "Dash-dash-board 1"
        },
        "creationTimestamp": "2025-01-24T10:38:57Z",
        "generation": 1,
        "name": "dash-dash-board-1",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"KttpW5ERbCrk6H8R\",\"tags\":[\"test\",\"test1\"],\"title\":\"Dash-dash-board-1\"}"
    }
}

Creating a dashboard

This endpoint creates a new dashboard.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required

Authentication required… The token must have “API management” and “Dashboards” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards' -d \
'
{
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "category-name",
            "metadata.deckhouse.io/title": "some name"
        },
        "name": "some-name"
    },
    "spec":
    {
        "definition": {...}
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "category-name",
            "metadata.deckhouse.io/title": "some name"
        },
        "creationTimestamp": "2025-01-24T10:41:12Z",
        "generation": 1,
        "name": "some-name",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"czvSGOukIQTWEE19\",\"tags\":[\"test\"],\"title\":\"some name\"}"
    }
}

Updating a dashboard

This endpoint updates an existing dashboard.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: dashboard name

Authentication required… The token must have “API management” and “Dashboards” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name' -d \
'
{
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "new-category"
        }
    },
    "spec":
    {
        "definition": {...}
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityDashboard",
    "metadata":
    {
        "annotations":
        {
            "metadata.deckhouse.io/category": "new-category",
            "metadata.deckhouse.io/title": "Dash-dash-board-1"
        },
        "creationTimestamp": "2025-01-24T10:45:15Z",
        "generation": 1,
        "name": "dash-dash-board-1",
        "namespace": "spicy-space-1",
        "resourceVersion": 1
    },
    "spec":
    {
        "definition": "{\"uid\":\"yS1Qy46y6x01bFJI\",\"tags\":[\"test\",\"another-test\"],\"title\":\"Dash-dash-board-1\"}"
    }
}

Deleting a dashboard

This endpoint deletes an existing dashboard.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name. Required
name: dashboard name

Authentication required… The token must have “API management” and “Dashboards” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitydashboards/:name'

Errors when creating or updating dashboards

If the request to create or update a dashboard contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Name has already been taken"}

Workspaces

Workspace parameters

metadata.name: workspace name, must be unique, lowercase Latin letters and - are allowed
metadata.generation: workspace version
metadata.resourceVersion: global workspace version
metadata.creationTimestamp: workspace creation date/time

Getting the list of workspaces

This endpoint returns the list of workspaces. GET /api/v1/observability.deckhouse.io/spaces

Authentication required… The token must have “API management” and “Workspaces” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilitySpacesList",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilitySpace",
            "metadata":
            {
                "creationTimestamp": "2025-03-14T06:07:50Z",
                "generation": 1,
                "name": "example-space",
                "resourceVersion": 1
            },
            "spec":
            {}
        }
    ]
}

Getting a workspace

This endpoint returns a workspace by name.

GET /api/v1/observability.deckhouse.io/spaces/:name

URL path parameters:

name: workspace name. Required

Authentication required… The token must have “API management” and “Workspaces” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilitySpace",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:07:50Z",
      "generation": 1,
      "name": "example-space",
      "resourceVersion": 1
  },
  "spec":
  {}
}

Creating a workspace

This endpoint creates a new workspace.

POST /api/v1/observability.deckhouse.io/spaces

Authentication required… The token must have “API management” and “Workspaces” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces' -d \
'
{
    "kind": "ObservabilitySpace",
    "metadata":
    {
        "name": "some-name"
    }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilitySpace",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:07:50Z",
      "generation": 1,
      "name": "some-name",
      "resourceVersion": 1
  },
  "spec":
  {}
}

Deleting a workspace

This endpoint deletes an existing workspace.

DELETE /api/v1/observability.deckhouse.io/spaces/:name

URL path parameters:

name: workspace name

Authentication required… The token must have “API management” and “Workspaces” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:name'

Errors when creating workspaces

If the request to create a workspace contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Space name has already been taken"}

Projects

Project parameters

metadata.name: project name, must be unique within the workspace, lowercase Latin letters and - are allowed
metadata.generation: project version
metadata.resourceVersion: global project version
metadata.creationTimestamp: project creation date/time
spec.description: project description
spec.auto-monitoring: flag indicating whether auto-monitoring is used in the specified project.

Getting the list of workspace projects

This endpoint returns the list of projects in a workspace.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects

URL path parameters:

space_name: workspace name. Required

Authentication required… The token must have “API management” and “Projects” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityProjectsList",
    "metadata": {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityProject",
            "metadata":
            {
                "creationTimestamp": "2025-03-14T06:06:41Z",
                "generation": 1,
                "name": "some-project",
                "resourceVersion": 1
            },
            "spec":
            {
                "description": "project description",
                "auto-monitoring": true
            }
        }
    ]
}

Getting a project

This endpoint returns a project by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

URL path parameters:

space_name: workspace name. Required
name: project name. Required

Authentication required… The token must have “API management” and “Projects” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "project description",
      "auto-monitoring": true
  }
}

Creating a project

This endpoint creates a new project.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects

URL path parameters:

space_name: workspace name. Required

Authentication required… The token must have “API management” and “Projects” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects' -d \
'
{
    "kind": "ObservabilityProject",
    "metadata":
    {
      "name": "some-name"
    },
    "spec":
    {
      "description": "project description",
      "auto-monitoring": true
    }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "project description",
      "auto-monitoring": true
  }
}

Updating a project

This endpoint updates an existing project.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

URL path parameters:

space_name: workspace name. Required
name: project name. Required

Authentication required… The token must have “API management” and “Projects” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name' -d \
'
{
    "kind": "ObservabilityProject",
    "spec":
    {
        "description": "updated description",
        "auto-monitoring": false
    }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityProject",
  "metadata":
  {
      "creationTimestamp": "2025-03-14T06:06:41Z",
      "generation": 1,
      "name": "some-project",
      "resourceVersion": 1
  },
  "spec":
  {
      "description": "updated description",
      "auto-monitoring": false
  }
}

Deleting a project

This endpoint deletes an existing project.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name

URL path parameters:

space_name: workspace name. Required
name: project name. Required

Authentication required… The token must have “API management” and “Projects” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:name'

Errors when creating or updating a project

If the request to create or update a project contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Project name has already been taken"}

Notification Channels

Notification channel parameters

metadata.name: notification channel name, must be unique within the project, lowercase Latin letters and - are allowed
metadata.generation: notification channel version
metadata.resourceVersion: global notification channel version
metadata.creationTimestamp: notification channel creation date/time
spec.type: notification channel type, allowed values: Email, Telegram, Webhook, Slack

Email notification channel parameters

spec.email.from: email address from which messages will be sent
spec.email.smtp.address: mail server address
spec.email.smtp.auth.username: username for mail server authentication
spec.email.smtp.auth.password: password for mail server authentication
spec.email.stmp.requireTLS: flag indicating whether TLS is required when sending messages. Allowed values: true / false
spec.email.template: message template. Returned in responses, not modifiable via API

Telegram notification channel parameters

spec.telegram.apiUrl: Telegram API URL, by default the standard https://api.telegram.org is used
spec.telegram.apiToken: authorization token for the Telegram channel
spec.telegram.template: message template. Returned in responses, not modifiable via API

Slack notification channel parameters

spec.slack.apiURL: Slack URL for sending notifications
spec.slack.template: message template. Returned in responses, not modifiable via API

Webhook notification channel parameters

spec.webhook.url: URL for sending messages

Getting the list of project channels

This endpoint returns the list of project notification channels and public notification channels. For public channels, only the name and type are returned, without channel parameters.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels

URL path parameters:

space_name: workspace name. Required
project_name: project name

Authentication required… The token must have “API management” and “Notification channels” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannelsList",
  "metadata": {},
  "items": [
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityNotificationChannel",
      "metadata": {
        "name": "example-channel",
        "creationTimestamp": "2025-03-19T06:12:20Z",
        "generation": 1,
        "resourceVersion": "1"
      },
      "spec": {
        "type": "Email",
        "email": {
          "from": "no-reply@email.com",
          "smtp": {
            "address": "smtp.example.server.com:555",
            "auth": {
              "username": "username",
              "password": "password"
            },
            "requireTLS": true
          },
          "template": "..."
        }
      }
    },
  ]
}

Getting a notification channel

This endpoint returns a project notification channel by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: channel name. Required

Authentication required… The token must have “API management” and “Notification channels” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata": {
    "name": "example-channel",
    "creationTimestamp": "2025-03-19T06:12:20Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "type": "Email",
    "email": {
      "from": "no-reply@email.com",
      "smtp": {
        "address": "smtp.example.server.com:555",
        "auth": {
          "username": "username",
          "password": "password"
        },
        "requireTLS": true
      },
      "template": "..."
    }
  }
}

Creating a notification channel

This endpoint creates a new project notification channel.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels

URL path parameters:

space_name: workspace name. Required
project_name: project name

Authentication required… The token must have “API management” and “Notification channels” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "new-channel"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          }
      }
  }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "new-channel",
      "creationTimestamp": "2025-03-28T05:04:45Z",
      "generation": 1,
      "resourceVersion": "1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          },
          "template": null
      }
  }
}

Updating a notification channel

This endpoint updates a project notification channel.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: channel name. Required

Authentication required… The token must have “API management” and “Notification channels” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "some-channel-1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from2@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          }
      }
  }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationChannel",
  "metadata":
  {
      "name": "some-channel-1",
      "creationTimestamp": "2025-03-28T05:08:42Z",
      "generation": 1,
      "resourceVersion": "1"
  },
  "spec":
  {
      "type": "Email",
      "email":
      {
          "from": "from2@email.com",
          "smtp":
          {
              "address": "smtp.example.com:444",
              "auth":
              {
                  "username": "username",
                  "password": "password"
              },
              "requireTLS": true
          },
          "template": null
      }
  }
}

Deleting a notification channel

This endpoint deletes an existing project notification channel.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: channel name. Required

Authentication required… The token must have “API management” and “Notification channels” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:name'

Errors when creating or updating a notification channel

If the request to create or update a channel contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Name has already been taken"}

Notification Rules

Notification rule parameters

metadata.name: notification rule name, must be unique within the project, lowercase Latin letters and - are allowed
metadata.generation: notification rule version
metadata.resourceVersion: global notification rule version
metadata.creationTimestamp: notification rule creation date/time
spec.alert.selector.matchExpressions.items: array of notification selectors, described below
spec.notification.channel.name: notification channel name
spec.notification.parameters: notification parameters, depend on the channel type, described below
spec.notification.repeatInterval: repeat notification interval, string value in the form ’30s’, ‘5m’, ‘1h’ (seconds, minutes, and hours are allowed)

Notification selector

key: label name
operator: string operator designation, allowed values: Equal, NotEqual, Regex, NotRegex
value: string label value for comparison by the operator

Email notification channel parameters

spec.notification.parameters.emails: array of email addresses to which the notification is sent

Telegram notification channel parameters

spec.notification.parameters.chatIds: array of chat identifiers to which notifications are sent

Slack notification channel parameters

spec.notification.parameters.channels: array of Slack channel names to which the notification is sent

Webhook notification channel parameters

Notification rules for webhook channels do not use parameters.

Getting the list of channel notification rules

This endpoint returns the list of notification rules for a workspace notification channel.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies

URL path parameters:

space_name: workspace name. Required
project_name: project name

Authentication required… The token must have “API management” and “Notification rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPoliciesList",
  "metadata": {},
  "items":
  [
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityNotificationPolicy",
      "metadata": {
        "name": "test-rule",
        "creationTimestamp": "2025-03-28T06:42:47Z",
        "generation": 1,
        "resourceVersion": "1"
      },
      "spec": {
        "alert": {
          "selector": {
            "matchExpressions": {
              "items":
              [
                {
                  "key": "severity",
                  "operator": "Equal",
                  "value": "critical"
                }
              ]
            }
          }
        },
        "notification":
        {
          "channel":
          {
            "kind": "ObservabilityNotificationChannel",
            "name": "some-channel-1",
            "parameters": { "emails": ["test@email.com"] }
          },
          "repeatInterval": "30s"
        }
      }
    }
  ]
}

Getting a notification rule

This endpoint returns a project notification rule by name.

GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: rule name. Required

Authentication required… The token must have “API management” and “Notification rules” permissions

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:00:54Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": ["test@email.com"]
        }
      },
      "repeatInterval": "30s"
    }
  }
}

Creating a notification rule

This endpoint creates a new project notification rule.

POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies

URL path parameters:

space_name: workspace name. Required
project_name: project name

Authentication required… The token must have “API management” and “Notification rules” permissions

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationchannels/:notification_channel_name/observabilitynotificationpolicies' -d \
'
{
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "45s"
    }
  }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:12:41Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "critical"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "45s"
    }
  }
}

Updating a notification rule

This endpoint updates a project notification rule.

PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: rule name. Required

Authentication required… The token must have “API management” and “Notification rules” permissions

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name' -d \
'
{
  "kind": "ObservabilityNotificationChannel",
  "metadata": {
    "name": "test-rule"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "warning"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "46s"
    }
  }
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityNotificationPolicy",
  "metadata": {
    "name": "test-rule",
    "creationTimestamp": "2025-03-28T07:16:02Z",
    "generation": 1,
    "resourceVersion": "1"
  },
  "spec": {
    "alert": {
      "selector": {
        "matchExpressions": {
          "items": [
            {
              "key": "severity",
              "operator": "Equal",
              "value": "warning"
            }
          ]
        }
      }
    },
    "notification": {
      "channel": {
        "kind": "ObservabilityNotificationChannel",
        "name": "some-giper-channel-1",
        "parameters": {
          "emails": [
            "first@email.com",
            "second@email.com"
          ]
        }
      },
      "repeatInterval": "46s"
    }
  }
}

Deleting a notification rule

This endpoint deletes an existing project notification rule.

DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name

URL path parameters:

space_name: workspace name. Required
project_name: project name
name: rule name. Required

Authentication required… The token must have “API management” and “Notification rules” permissions

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/observabilitynotificationpolicies/:name'

Errors when creating or updating a notification rule

If the request to create or update a rule contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Name has already been taken"}

Users

User parameters

metadata.external_id: external user identifier (e.g., OIDC ID)
metadata.generation: user version
metadata.resourceVersion: global user version
metadata.creationTimestamp: user creation date/time
spec.email: user email
spec.firstName: user first name
spec.lastName: user last name
spec.displayName: full name

Getting the list of users

This endpoint returns the list of users. GET /api/v1/observability.deckhouse.io/users

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityUsersList",
    "metadata":
    {},
    "items":
    [
        {
            "apiVersion": "observability.deckhouse.io/v1alpha1",
            "kind": "ObservabilityUser",
            "metadata":
            {
                "creationTimestamp": "2025-05-13T07:14:10Z",
                "generation": 1,
                "externalId": "1",
                "resourceVersion": "1"
            },
            "spec":
            {
                "email": "mail1+memaybe@example.com",
                "firstName": "Jason",
                "lastName": "Bourne-1th",
                "displayName": null
            }
        }
    ]
}

Getting a user

This endpoint returns a user by external identifier.

GET https://api.dop.example.com/api/v1/observability.deckhouse.io/users/:external_id

URL path parameters:

external_id: external user identifier. Required

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityUser",
  "metadata":
  {
      "creationTimestamp": "2025-05-13T07:14:10Z",
      "generation": 1,
      "externalId": "1",
      "resourceVersion": "1"
  },
  "spec":
  {
      "email": "mail1+memaybe@example.com",
      "firstName": "Jason",
      "lastName": "Bourne-1th",
      "displayName": null
  }
}

Creating a user

This endpoint creates a new user. To send requests to create a user, OIDC role provisioning must be disabled.

POST https://api.dop.example.com/api/v1/observability.deckhouse.io/users

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users' -d \
'
{
    "kind": "ObservabilityUser",
    "metadata":
    {
        "externalId": "1"
    },
    "spec":
    {
        "email": "some@email.com",
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "displayName": "Ivan Ivanov"
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityUser",
    "metadata":
    {
        "creationTimestamp": "2025-05-16T12:43:48Z",
        "generation": 1,
        "externalId": "1",
        "resourceVersion": "1"
    },
    "spec":
    {
        "email": "some@email.com",
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "displayName": "Ivan Ivanov"
    }
}

Updating a user

This endpoint updates an existing user. To send requests to update a user, OIDC role provisioning must be disabled.

PUT /api/v1/observability.deckhouse.io/users/:external_id

external_id: external user identifier. Required

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1' -d \
'
{
    "kind": "ObservabilityUser",
    "metadata":
    {
        "externalId": "1"
    },
    "spec":
    {
        "email": "updated@email.com",
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "displayName": "Ivan Ivanov"
    }
}
'

Example response:

{
    "apiVersion": "observability.deckhouse.io/v1alpha1",
    "kind": "ObservabilityUser",
    "metadata":
    {
        "creationTimestamp": "2025-05-16T12:49:06Z",
        "generation": 1,
        "externalId": "1",
        "resourceVersion": "1"
    },
    "spec":
    {
        "email": "updated@email.com",
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "displayName": "Ivan Ivanov"
    }
}

Deleting a user

This endpoint deletes an existing user. To send requests to delete a user, OIDC role provisioning must be disabled.

DELETE /api/v1/observability.deckhouse.io/users/:external_id

external_id: external user identifier. Required

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/1'

Errors when creating or updating a user

If the request to create or update a user contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Email has already been taken"}

If OIDC role provisioning is enabled, attempts to modify user roles will return the error “OIDC user roles enabled”.

User Roles

Description of the user role model.

User role parameters

metadata.generation: user version
metadata.resourceVersion: global user version
metadata.creationTimestamp: user creation date/time
spec.scope: type of object the user role is bound to (allowed values: GlobalScope, Space, Project)
spec.role: user role, allowed values: super_admin, admin, user, viewer, ro_super_admin
spec.space: workspace the user role is bound to
spec.project: project the user role is bound to

Getting the list of user roles

This endpoint returns the list of user roles. GET /api/v1/observability.deckhouse.io/users/:external_id/memberships

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/observability.deckhouse.io/users/:external_id/memberships'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityUserMembershipsList",
  "metadata": {},
  "items":
  [
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityUserMembership",
      "metadata":
      {
          "creationTimestamp": "2025-05-13T05:21:39Z",
          "generation": 1,
          "resourceVersion": 1
      },
      "spec":
      {
          "scope": "GlobalScope",
          "role": "admin"
      }
    },
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityUserMembership",
      "metadata":
      {
          "creationTimestamp": "2025-05-13T05:21:39Z",
          "generation": 1,
          "resourceVersion": 1
      },
      "spec":
      {
          "scope": "Space",
          "role": "user",
          "space": "spicy-space-1"
      }
    },
    {
      "apiVersion": "observability.deckhouse.io/v1alpha1",
      "kind": "ObservabilityUserMembership",
      "metadata":
      {
          "creationTimestamp": "2025-05-13T05:21:39Z",
          "generation": 1,
          "resourceVersion": 1
      },
      "spec":
      {
          "scope": "Project",
          "role": "viewer",
          "space": "spicy-space-1",
          "project": "umbrella-project-1"
      }
    }
  ]
}

Updating user roles

This endpoint updates user roles. To send requests to update roles, OIDC role provisioning must be disabled.

POST /api/v1/observability.deckhouse.io/users/:external_id/memberships

URL path parameters:

external_id: external user identifier. Required

Authentication required… The token must have “User management” permissions, and the token must be bound to the entire system (global scope)

Example request:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <API-token>" \
  'https://api.dop.example.com/api/v1/users/1/memberships' -d \
'
{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityUserMembershipsList",
  "metadata": {},
  "items":
  [
    {
      "spec":
      {
          "scope": "GlobalScope",
          "role": "admin"
      }
    },
    {
      "spec":
      {
          "scope": "Space",
          "role": "user",
          "space": "spicy-space-1"
      }
    },
    {
      "spec":
      {
          "scope": "Project",
          "role": "viewer",
          "space": "spicy-space-1",
          "project": "umbrella-project-1"
      }
    }
  ]
}
'

Example response:

{
  "apiVersion": "observability.deckhouse.io/v1alpha1",
  "kind": "ObservabilityUserMembershipsList",
  "metadata": {},
  "items":
  [
    {
      "spec":
      {
          "scope": "GlobalScope",
          "role": "admin"
      }
    },
    {
      "spec":
      {
          "scope": "Space",
          "role": "user",
          "space": "spicy-space-1"
      }
    },
    {
      "spec":
      {
          "scope": "Project",
          "role": "viewer",
          "space": "spicy-space-1",
          "project": "umbrella-project-1"
      }
    }
  ]
}

Errors when creating or updating user roles

If the request to update user roles contains invalid data, the response will have a 4xx status with an error message:

{"error":"Validation failed: Memberships is invalid"}

If OIDC role provisioning is enabled, attempts to modify user roles will return the error “OIDC user roles enabled”.