The module lifecycle stage: General Availability
The module has requirements for installation
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.
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
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.timeoutflag.
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
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 (durationformat 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
URL parameters:
match[]=<series_selector>: repeated argument for the series selector that selects the returned series. At least onematch[]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
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
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/valuesResponse:
{
"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
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
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:forwardorbackward. Default isbackward.
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)' | jqResponse:
{
"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
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 theendvalue is in the future, the start time is calculated as this duration before the current moment. Any specified value of thestartparameter takes precedence oversince.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,5mmeans a duration of 5 minutes. Default is a dynamic value based onstartandend. 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 thestepparameter, see explanation below.direction: Determines the sort order of logs. Supported values areforward(ascending) orbackward(descending). Default isbackward.
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' | jqResponse:
{
"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
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" | jqResponse:
{
"status": "success",
"data": [
"foo",
"bar",
"baz"
]
}Query label values
GET /loki/api/v1/label/<name>/values
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" | jqResponse:
{
"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/ExportJaeger 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 inkey=valueformat. 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 allowedmetadata.generation: trigger versionmetadata.resourceVersion: global trigger versionmetadata.creationTimestamp: trigger creation date/timemetadata.annotations: list of trigger annotations in name-value format. Currently the trigger category annotationmetadata.deckhouse.io/categoryis supportedspec.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 expressionoperator: operator, allowed values:Equal | GreaterThan | LessThan | LessThanOrEqual | GreaterThanOrEqual | NotEqualseverity: 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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_name: project name. Requiredname: 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 allowedmetadata.generation: metric versionmetadata.resourceVersion: global metric versionmetadata.creationTimestamp: metric creation date/timemetadata.annotations: list of metric annotations in name-value format. Currently the metric category annotationmetadata.deckhouse.io/categoryis supportedspec.expression: metric expression, must be a valid Prometheus expression.spec.alertMetadata.targetMetric: metric parametersname: 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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_name: project name. Requiredname: 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"}Web-monitoring Sites
Site parameters
metadata.name: site display name, must be unique within the projectmetadata.generation: site versionmetadata.resourceVersion: global site versionmetadata.creationTimestamp: site creation date/timespec.host: domain name or IP address to monitor (e.g.example.com)spec.uiEditable: whether the site may be edited through the DOP UI. Optional boolean, defaults totrue. When set tofalsethe UI marks the site as API-managed: the “edit” action is disabled and a badge is shown, while creation, update via API and deletion (both UI and API) remain available. The field is omitted from API responses when it is at its default value (true); only sites withuiEditable: falseinclude the field. Thewebmon-cliutility forwards the value verbatim from YAML (uiEditableat unit-defaultsor per-target level) and omits the field when YAML does not set it — so existing values stored in DOP are preserved acrosssyncruns.spec.period: probe interval, string in format\d+(s|m), maximum 60 seconds. Examples:"20s","45s","1m"spec.ping: enable ICMP ping probe (true/false)spec.probeAllResolvedIPs: probe all resolved IPs instead of just the first one (true/false)spec.hosts: array of specific IP addresses to probe instead of DNS resolution (optional)spec.zones: array of zone names where the site should be monitored. If not specified — monitored from all zonesspec.siteLabels: Prometheus labels added to all metrics for this sitespec.checkLabels: labels for all checks (e.g.alert=yes)spec.requestDefaults: default HTTP request settings. Inherited by HTTP probes only (TCP/DNS probes ignore site-level request).scheme:"http"or"https"timeout: string, format\d+(ms|s|m), max300sheaders: array of{name, value}— both fields are required strings;namemust be non-empty;valuemay be an empty string but must be a String (nonil, no missing key, no non-string types)- Probe-specific keys (
port,method,path,basicAuth,data,disableHttp2ForHttps) are not allowed at this level
spec.probes: array of probe definitionsname: probe nameprobeType:http,tcp, ordnsperiod: probe-specific interval override (optional). Effectiveperiodmust be>=every check’sresponseTime.maxrequest/tcp/dns: probe configuration depending on typerequest.method(HTTP):GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS,TRACE(case-normalized to uppercase)request.scheme(HTTP):"http"or"https"request.timeout/tcp.timeout/dns.timeout: string, format\d+(ms|s|m), max300srequest.disableHttp2ForHttps(HTTP): string"true"or"false"(must be quoted)dns.type:A,AAAA,CNAME,MX,NS,TXT,SOA,SRV,PTR,CAA(case-normalized to uppercase)port(HTTP/TCP): integer1..65535
checks: array of check definitions-
name: check name -
Check fields by probe type:
probeType Allowed check fields httpstatus,responseTime,bodyMatch,bodySize,contentType,location,sslBasicConstraintsValid,certValidDays,sslValidDays,headers,cookiestcpconnected,responseTime,sslBasicConstraintsValid,certValidDays,sslValidDaysdnsgotAnswer,answerMatch,responseTime -
responseTime.max: string, format\d+(ms|s|m)(noh)
-
Getting the list of project web-monitoring sites
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
Authentication required… The token must have “API management” and “Web-monitoring” 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/webmonitoringsites'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": {},
"items": [
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityWebMonitoringSite",
"metadata": {
"creationTimestamp": "2026-02-20T10:00:00Z",
"generation": 1,
"name": "api-example-com",
"resourceVersion": "1"
},
"spec": {
"host": "api.example.com",
"period": "20s",
"ping": true,
"probeAllResolvedIPs": false,
"hosts": ["93.184.216.34"],
"zones": ["world"],
"siteLabels": {"project": "myproj"},
"checkLabels": {"alert": "yes"},
"probes": [
{
"name": "https-main",
"probeType": "http",
"request": {"scheme": "https", "path": "/healthz"},
"checks": [
{"name": "status-200", "status": [200]},
{"name": "response-time", "responseTime": {"max": "5s"}}
]
}
]
}
}
]
}Getting a web-monitoring site
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites/:name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: site name. Required
Authentication required… The token must have “API management” and “Web-monitoring” 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/webmonitoringsites/api-example-com'Creating a web-monitoring site
POST /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
Authentication required… The token must have “API management” and “Web-monitoring” permissions
Example request:
$ curl -X POST -H "X-Auth-Token: <API-token>" \
-H "Content-Type: application/json" \
'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites' \
-d '{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityWebMonitoringSite",
"metadata": {"name": "api-example-com"},
"spec": {
"host": "api.example.com",
"period": "20s",
"ping": true,
"zones": ["world"],
"probes": [
{
"name": "https-main",
"probeType": "http",
"request": {"scheme": "https", "path": "/healthz"},
"checks": [
{"name": "status-200", "status": [200]}
]
}
]
}
}'Updating a web-monitoring site
PUT /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites/:name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: site name. Required
Authentication required… The token must have “API management” and “Web-monitoring” permissions
The request body format is the same as for creating a site. Probes and checks are fully replaced on update.
Deleting a web-monitoring site
DELETE /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites/:name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: site name. Required
Authentication required… The token must have “API management” and “Web-monitoring” permissions
Example request:
$ curl -X DELETE -H "X-Auth-Token: <API-token>" \
'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/webmonitoringsites/api-example-com'Returns 204 No Content on success.
Hardware Inventory
This is a read-only API for the hardware inventory of bare-metal servers. The Storage Topology and OS Storage Stack sections of the web interface are not exposed through it.
The API covers the servers of one project that have the bare_metal type, are not blacklisted, are not archived, and have been synchronized with the inventory. Archiving a project permanently deletes all of its inventory data: components, installations, slots, datacenters, racks and placements, including the placements of SNMP network devices in those datacenters (the devices themselves are kept). Unarchiving does not bring the data back — the inventory reappears only after the next synchronization, and placements have to be created again.
All endpoints require the permission_api_cmdb_read permission. It can only be granted to a project-scoped token, and it cannot be combined with metrics, logs or traces on the same token, so the inventory needs a token of its own. The write permission does not imply the read one, and there are no write routes yet.
Inventory parameters
List endpoints return their items in a wrapper with pagination:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 128, "totalPages": 3 },
"items": []
}The change history of a server is the one list endpoint without pagination: its metadata carries limit and returned instead.
Server (ObservabilityHost):
metadata.name: server name as the agent reports itmetadata.creationTimestamp: date/time the server record was createdspec.hostType: server type, alwaysbare_metalherespec.health.scanTime: date/time of the last inventory scanspec.health.scanStale:truewhen the last scan is older than two hours or has never happenedspec.health.partial:truewhen the last scan did not cover the whole configurationspec.health.synced:truewhen the server is synchronized with the inventoryspec.system.uuid,spec.system.serial: system UUID and serial number from SMBIOSspec.location: current placement —datacenter,rack,rackUStart,rackUHeight,rackFace.nullwhen the server is not placedspec.singletons: units that exist in a single copy —system,baseboard,bios,chassis. Their fields are passed through from what the agent read out of SMBIOS, so the exact set depends on the server;manufacturerorvendor,productorversion, andserialare the usual ones. Only in the response of a single serverspec.summary: configuration totals —cpuTotal,cpuPopulated,memoryTotal,memoryPopulated,memoryBytes,disksTotal,disksBytes,nicsTotal,gpusTotal. Only in the response of a single server
Component (ObservabilityHardwareComponent):
metadata.name: component key, unique within the projectspec.componentType: component kind —cpu,memory,disk,controller,nic,gpu,psu,pcispec.componentKey,spec.manufacturer,spec.model,spec.serialNumber,spec.partNumber: identification of the unit.manufactureris empty for disks — a disk reports either a generic vendor string or none at all, so the brand is part ofmodelspec.wwn,spec.macAddress,spec.capacityBytes,spec.transport,spec.rotational: fields of specific kinds — WWN and interface for disks, MAC for network cardsspec.lifecycleState:present,suspect_missingorremovedspec.hostName,spec.slotType,spec.slotKey: where the component is installed nowspec.lastSeenAt: date/time the component was last seen in a scanspec.installations: the full history of installations —hostName,slotType,slotKey,installedAt,removedAt. Only in the response of a component by key
Slot (ObservabilityHardwareSlot):
spec.slotType: slot kind —cpu_socket,memory_slot,storage_location,system_slot,psu_slotspec.slotKey: slot keyspec.occupied:truewhen a component is installed in the slotspec.componentKey: key of the component in the slotspec.lastSeenAt: date/time the slot was last seen in a scan
Change event (ObservabilityHardwareTimelineEvent):
spec.eventType:installedorremovedspec.componentKey,spec.componentType: the component the event is aboutspec.hostName,spec.slotType,spec.slotKey: where it happenedspec.occurredAt: date/time of the event
Datacenter (ObservabilityDatacenter) and rack (ObservabilityEquipmentRack):
spec.address,spec.description,spec.racksCount: datacenter fieldsspec.racks: names of the racks. Only in the response of a single datacenterspec.datacenter,spec.uHeight,spec.occupiedUnits: rack fieldsspec.placements: what is placed in the rack —hostName,rackUStart,rackUHeight,rackFace. Only in the response of a single rack
Note that motherboard, bios and chassis are not component kinds: they are stored with the server as single units and are available in spec.singletons, not through the component endpoints.
Getting the list of project servers
This endpoint returns the list of bare-metal servers of the project.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
URL query parameters:
host: substring of the server name, at least 2 characters, case-insensitive. OptionalhostSerial: substring of the system serial number from SMBIOS, at least 2 characters. OptionalhostUuid: substring of the system UUID from SMBIOS, at least 2 characters. OptionalhostIdentity: substring of the system serial number or UUID, at least 2 characters. OptionalmotherboardSerial: substring of the motherboard serial number, at least 2 characters. OptionalchassisSerial: substring of the chassis serial number, at least 2 characters. Optionaldatacenter: exact datacenter name. Only the current placement is considered. Optionalrack: exact rack name. Requiresdatacenter, because rack names are unique only within a datacenter; on its own it returns 400invalid_parameter. Optionalhistorical:truealso returns the servers whose last scan is older than two hours or has never happened. Defaults tofalse. Optionalpartial:truereturns only the servers whose last scan did not cover the whole configuration. Optionalkind: component kind —cpu,memory,disk,controller,nic,gpu,psu,pci. Optionalserial: substring of the component serial number, at least 2 characters. Optionalmanufacturer: substring of the component manufacturer, at least 2 characters. Empty for disks — the brand is part ofmodel. Optionalmodel: substring of the component model, at least 2 characters. Optionalkey: substring of the component key, at least 2 characters. Optionalwwn: substring of the WWN, at least 2 characters. Only together withkind=disk, otherwise 400wwn_not_applicable. Optionalmac: substring of the MAC address, at least 2 characters. Only together withkind=nic, otherwise 400mac_not_applicable. Optionaltransport: disk interface —nvme,sas,sata,scsi,virtio,unknown. Only together withkind=disk. Optionalrotational:truefor hard drives,falsefor SSD and NVMe. Only together withkind=disk. Components whose value is not set match neither. Optionalstate: component state —present(default),suspect_missing,removed. Optionalpage: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
Hardware parameters select servers by what is installed in them: ?kind=disk&model=MZ7LH returns the servers holding such a disk. Several parameters are combined with AND.
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hosts?host=web-&perPage=50'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 128, "totalPages": 3 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHost",
"metadata":
{
"name": "web-01.example.com",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"hostType": "bare_metal",
"health": { "scanTime": "2026-07-29T11:00:00Z", "scanStale": false, "partial": false, "synced": true },
"system": { "uuid": "4c4c4544-0033-3510-8053-b8c04f434332", "serial": "ABC123" },
"location": { "datacenter": "dc-msk-1", "rack": "R12", "rackUStart": 20, "rackUHeight": 2, "rackFace": "front" }
}
}
]
}Getting a server
This endpoint returns one server by name, together with its single units and configuration totals.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/:name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: server name, exact match. Required
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hosts/web-01.example.com'Example response:
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHost",
"metadata":
{
"name": "web-01.example.com",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"hostType": "bare_metal",
"health": { "scanTime": "2026-07-29T11:00:00Z", "scanStale": false, "partial": false, "synced": true },
"system": { "uuid": "4c4c4544-0033-3510-8053-b8c04f434332", "serial": "ABC123" },
"singletons":
{
"system": { "manufacturer": "Dell Inc.", "product": "PowerEdge R650", "serial": "ABC123" },
"baseboard": { "manufacturer": "Dell Inc.", "product": "0K2TT4", "serial": "MB-77219" },
"bios": { "vendor": "Dell Inc.", "version": "1.10.2" },
"chassis": { "manufacturer": "Dell Inc.", "serial": "CH-40188" }
},
"summary":
{
"cpuTotal": 2, "cpuPopulated": 2,
"memoryTotal": 16, "memoryPopulated": 8, "memoryBytes": 274877906944,
"disksTotal": 2, "disksBytes": 3840755982336,
"nicsTotal": 1, "gpusTotal": 0
},
"location": { "datacenter": "dc-msk-1", "rack": "R12", "rackUStart": 20, "rackUHeight": 2, "rackFace": "front" }
}
}Getting the components of a server
This endpoint returns the components installed in one server.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/:name/hardwarecomponents
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: server name, exact match. Required
URL query parameters:
kind: component kind —cpu,memory,disk,controller,nic,gpu,psu,pci. Optionalstate: component state —present(default),suspect_missing,removed. Optionalpage: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
There is no historical parameter here — the state of a component is selected with state.
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hosts/web-01.example.com/hardwarecomponents?kind=disk'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 2, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareComponent",
"metadata":
{
"name": "wwn:0x5002538e00000001",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"componentType": "disk",
"componentKey": "wwn:0x5002538e00000001",
"manufacturer": null,
"model": "SAMSUNG MZQLB1T9HAJR-00007",
"serialNumber": "S439NA0R202605",
"wwn": "0x5002538e00000001",
"macAddress": null,
"capacityBytes": 1920383410176,
"transport": "nvme",
"rotational": false,
"lifecycleState": "present",
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"lastSeenAt": "2026-07-29T11:00:00Z"
}
}
]
}Getting the slots of a server
This endpoint returns the slots of one server, both occupied and empty.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/:name/hardwareslots
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: server name, exact match. Required
URL query parameters:
type: slot kind —cpu_socket,memory_slot,storage_location,system_slot,psu_slot. Optionalpage: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hosts/web-01.example.com/hardwareslots?type=memory_slot'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 16, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareSlot",
"metadata": { "name": "memory_slot:P0 CHANNEL A/DIMM 0" },
"spec":
{
"slotType": "memory_slot",
"slotKey": "P0 CHANNEL A/DIMM 0",
"occupied": true,
"componentKey": "mem:M391A4G43AB1-CWE:38F2A1B9",
"lastSeenAt": "2026-07-29T11:00:00Z"
}
}
]
}Getting the change history of a server
This endpoint returns the history of component installations and removals for one server, newest first.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/:name/hardwaretimeline
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: server name, exact match. Required
URL query parameters:
limit: number of events, an integer from 1 to 200. Defaults to50. OptionaleventType: event kind —installedorremoved. Optional
Moving a component between servers is recorded as two events, removed and installed, with the same timestamp.
This endpoint is not paginated: limit bounds the whole answer, page and perPage are ignored, and metadata reports limit and the number of events actually returned.
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hosts/web-01.example.com/hardwaretimeline?limit=50'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "limit": 50, "returned": 3 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareTimelineEvent",
"spec":
{
"eventType": "installed",
"componentKey": "wwn:0x5002538e00000001",
"componentType": "disk",
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"occurredAt": "2026-07-16T14:35:42Z"
}
}
]
}Searching for components
This endpoint searches for components across every server of the project and every kind of hardware.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hardwarecomponents
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
URL query parameters:
host: substring of the server name, at least 2 characters, case-insensitive. OptionalhostSerial: substring of the system serial number from SMBIOS, at least 2 characters. OptionalhostUuid: substring of the system UUID from SMBIOS, at least 2 characters. OptionalhostIdentity: substring of the system serial number or UUID, at least 2 characters. OptionalmotherboardSerial: substring of the motherboard serial number, at least 2 characters. OptionalchassisSerial: substring of the chassis serial number, at least 2 characters. Optionaldatacenter: exact datacenter name. Only the current placement is considered. Optionalrack: exact rack name. Requiresdatacenter, because rack names are unique only within a datacenter; on its own it returns 400invalid_parameter. Optionalhistorical:truealso returns the components of servers whose last scan is older than two hours. Defaults tofalse. Optionalpartial:truereturns only the components of servers whose last scan did not cover the whole configuration. Optionalkind: component kind —cpu,memory,disk,controller,nic,gpu,psu,pci. Optionalserial: substring of the component serial number, at least 2 characters. Optionalmanufacturer: substring of the component manufacturer, at least 2 characters. Empty for disks — the brand is part ofmodel. Optionalmodel: substring of the component model, at least 2 characters. Optionalkey: substring of the component key, at least 2 characters. Optionalwwn: substring of the WWN, at least 2 characters. Only together withkind=disk, otherwise 400wwn_not_applicable. Optionalmac: substring of the MAC address, at least 2 characters. Only together withkind=nic, otherwise 400mac_not_applicable. Optionaltransport: disk interface —nvme,sas,sata,scsi,virtio,unknown. Only together withkind=disk. Optionalrotational:truefor hard drives,falsefor SSD and NVMe. Only together withkind=disk. Components whose value is not set match neither. Optionalstate: component state —present(default),suspect_missing,removed. Optionalpage: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
Server parameters select components by the servers they sit in: ?datacenter=dc-msk-1&kind=disk returns the disks of that datacenter. Without kind the search spans every kind of hardware, which is how “find this serial number anywhere” works. The parameter set is the same as for the list of servers, so one query string can be moved between the two views of the same search.
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hardwarecomponents?serial=S439NA'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 1, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareComponent",
"metadata":
{
"name": "wwn:0x5002538e00000001",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"componentType": "disk",
"componentKey": "wwn:0x5002538e00000001",
"manufacturer": null,
"model": "SAMSUNG MZQLB1T9HAJR-00007",
"serialNumber": "S439NA0R202605",
"wwn": "0x5002538e00000001",
"macAddress": null,
"capacityBytes": 1920383410176,
"transport": "nvme",
"rotational": false,
"lifecycleState": "present",
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"lastSeenAt": "2026-07-29T11:00:00Z"
}
}
]
}Searching for components of one kind
This endpoint searches for components of one kind across every server of the project.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hardwarecomponents/:kind
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredkind: component kind —cpu,memory,disk,controller,nic,gpu,psu,pci. An unknown kind returns 404. Required
URL query parameters are the same as for the search across every kind. The kind in the path wins over the kind query parameter, so /hardwarecomponents/cpu?kind=disk searches for processors.
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hardwarecomponents/disk?model=SAMSUNG&rotational=false'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 2, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareComponent",
"metadata":
{
"name": "wwn:0x5002538e00000001",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"componentType": "disk",
"componentKey": "wwn:0x5002538e00000001",
"manufacturer": null,
"model": "SAMSUNG MZQLB1T9HAJR-00007",
"serialNumber": "S439NA0R202605",
"wwn": "0x5002538e00000001",
"macAddress": null,
"capacityBytes": 1920383410176,
"transport": "nvme",
"rotational": false,
"lifecycleState": "present",
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"lastSeenAt": "2026-07-29T11:00:00Z"
}
}
]
}Getting a component by key
This endpoint returns one component by its key, together with the full history of its installations.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hardwarecomponents/keys/:key
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredkey: component key, exact match, URL-encoded. Required
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/hardwarecomponents/keys/wwn%3A0x5002538e00000001'Example response:
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityHardwareComponent",
"metadata":
{
"name": "wwn:0x5002538e00000001",
"creationTimestamp": "2026-03-01T10:00:00Z"
},
"spec":
{
"componentType": "disk",
"componentKey": "wwn:0x5002538e00000001",
"manufacturer": null,
"model": "SAMSUNG MZQLB1T9HAJR-00007",
"serialNumber": "S439NA0R202605",
"wwn": "0x5002538e00000001",
"macAddress": null,
"capacityBytes": 1920383410176,
"transport": "nvme",
"rotational": false,
"lifecycleState": "present",
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"lastSeenAt": "2026-07-29T11:00:00Z",
"installations":
[
{
"hostName": "web-01.example.com",
"slotType": "storage_location",
"slotKey": "nvme0n1",
"installedAt": "2026-07-16T14:35:42Z",
"removedAt": null
}
]
}
}Exporting the inventory of servers to CSV
This endpoint returns the whole inventory of the project as a CSV file, one row per component, sorted by server name, component kind and component key.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/export
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
URL query parameters:
hostNames[]: server names, exact match, no more than 500. Repeated with the brackets:hostNames[]=web-01&hostNames[]=web-02. The bracketlesshostNames=takes a single name — repeating it keeps only the last value. Without the parameter the export covers the whole project. A prefix or a substring is not accepted here. Optionalstate: component state —present(default),suspect_missing,removed. Optional
There is no historical parameter and no freshness cut: unlike the list of servers, which by default hides a server whose last scan is older than two hours, the export covers every synchronized server of the project.
An export of more than 100 000 rows is refused with 413 export_too_large before the first byte is sent. The response has the text/csv; charset=utf-8 type with a UTF-8 BOM and is sent as an attachment named <project>-hosts-<YYYYMMDD>.csv.
Authentication required… The token must have the “Hardware inventory” read permission
Example request:
$ curl -H "X-Auth-Token: <API-token>" -OJ \
'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hosts/export?hostNames[]=web-01.example.com&hostNames[]=web-02.example.com'Example response:
hostName,componentKey,componentType,manufacturer,model,serialNumber,wwn,macAddress,capacityBytes,transport,lifecycleState,slotType,slotKey,lastSeenAt
web-01.example.com,wwn:0x5002538e00000001,disk,,SAMSUNG MZQLB1T9HAJR-00007,S439NA0R202605,0x5002538e00000001,,1920383410176,nvme,present,storage_location,nvme0n1,2026-07-29T11:00:00ZExporting components of one kind to CSV
This endpoint returns the components of one kind as a CSV file, sorted by server name and component key.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hardwarecomponents/:kind/export
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredkind: component kind —cpu,memory,disk,controller,nic,gpu,psu,pci. Required
URL query parameters:
hostNames[]: server names, exact match, no more than 500, repeated with the brackets the same way as in the export of the inventory of servers. Optionalstate: component state —present(default),suspect_missing,removed. Optional- the hardware parameters of the component search —
serial,manufacturer,model,key,wwn,mac,transport,rotational. Optional
The server parameters of the search — host, datacenter, rack and the rest — are ignored here: the set of servers is given by hostNames. historical is one of them, so the export has no freshness cut either and returns the components of the servers that the list of components hides by default. The columns, the 100 000 row limit and the response headers are the same as for the inventory of servers; the file is named <project>-<kind>-<YYYYMMDD>.csv.
Authentication required… The token must have the “Hardware inventory” read permission
Example request:
$ curl -H "X-Auth-Token: <API-token>" -OJ \
'https://api.dop.example.com/api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/hardwarecomponents/disk/export?rotational=false'Example response:
hostName,componentKey,componentType,manufacturer,model,serialNumber,wwn,macAddress,capacityBytes,transport,lifecycleState,slotType,slotKey,lastSeenAt
web-01.example.com,wwn:0x5002538e00000001,disk,,SAMSUNG MZQLB1T9HAJR-00007,S439NA0R202605,0x5002538e00000001,,1920383410176,nvme,present,storage_location,nvme0n1,2026-07-29T11:00:00ZGetting the list of datacenters
This endpoint returns the list of datacenters of the project.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/datacenters
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Required
URL query parameters:
page: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/datacenters'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 2, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityDatacenter",
"metadata": { "name": "dc-msk-1" },
"spec":
{
"address": "Moscow, Butlerova 7",
"description": "Main site",
"racksCount": 12
}
}
]
}Getting a datacenter
This endpoint returns one datacenter by name, together with the names of its racks.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/datacenters/:name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: datacenter name, exact match. Required
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/datacenters/dc-msk-1'Example response:
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityDatacenter",
"metadata": { "name": "dc-msk-1" },
"spec":
{
"address": "Moscow, Butlerova 7",
"description": "Main site",
"racksCount": 12,
"racks": ["R11", "R12", "R13"]
}
}Getting the list of racks
This endpoint returns the racks of one datacenter.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/datacenters/:name/racks
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: datacenter name, exact match. Required
URL query parameters:
page: page number, an integer from 1. Defaults to1. OptionalperPage: page size, an integer from 1 to 100. Defaults to50. Optional
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/datacenters/dc-msk-1/racks'Example response:
{
"apiVersion": "v1",
"kind": "List",
"metadata": { "page": 1, "perPage": 50, "totalItems": 12, "totalPages": 1 },
"items":
[
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityEquipmentRack",
"metadata": { "name": "R12" },
"spec":
{
"datacenter": "dc-msk-1",
"uHeight": 42,
"occupiedUnits": 18
}
}
]
}Getting a rack
This endpoint returns one rack together with what is placed in it.
GET /api/v1/observability.deckhouse.io/spaces/:space_name/projects/:project_name/inventory/datacenters/:name/racks/:rack_name
URL path parameters:
space_name: workspace name. Requiredproject_name: project name. Requiredname: datacenter name, exact match. Requiredrack_name: rack name, exact match. Required
Authentication required… The token must have the “Hardware inventory” read permission
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/inventory/datacenters/dc-msk-1/racks/R12'Example response:
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "ObservabilityEquipmentRack",
"metadata": { "name": "R12" },
"spec":
{
"datacenter": "dc-msk-1",
"uHeight": 42,
"occupiedUnits": 18,
"placements":
[
{
"hostName": "web-01.example.com",
"rackUStart": 20,
"rackUHeight": 2,
"rackFace": "front"
}
]
}
}Errors when requesting inventory
Errors are returned in the Kubernetes Status format:
{
"apiVersion": "observability.deckhouse.io/v1alpha1",
"kind": "Status",
"status": "Failure",
"code": 400,
"reason": "query_too_short",
"message": "parameter serial must be at least 2 characters"
}- 400
query_too_short: a substring parameter is shorter than 2 characters - 400
invalid_parameter:perPageis greater than 100,rackis given withoutdatacenter, or the value of an enumeration is not one of the allowed ones - 400
page_too_deep:pagemultiplied byperPageis greater than 100 000 - 400
wwn_not_applicable,mac_not_applicable,rotational_not_applicable,transport_not_applicable: a parameter is used with a component kind that does not have that field - 401: the token is missing, invalid, or has no read permission for the inventory. This response comes from the authentication gateway and is not in the
Statusformat - 404: the server, key, kind or datacenter does not exist. An unknown address and any method other than GET also return 404, not 405
- 413
export_too_large: the export would be larger than 100 000 rows. It is checked before the first byte is sent
A parameter that is valid but matches nothing is not an error: the response is an empty list. In particular, a filter on a field that a given kind of hardware does not have returns nothing rather than failing — this is why a disk has to be searched by model and not by manufacturer.
Dashboards
Dashboard parameters
metadata.name: dashboard name, must be unique (not used by another project dashboard or global dashboard), lowercase Latin letters and-are allowedmetadata.generation: dashboard versionmetadata.resourceVersion: global dashboard versionmetadata.creationTimestamp: dashboard creation date/timemetadata.annotations: list of dashboard annotations in name-value format. Currently the following annotations are supported:metadata.deckhouse.io/category- dashboard categorymetadata.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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_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. Requiredproject_name: project name. Requiredname: 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. Requiredproject_name: project name. Requiredname: 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 allowedmetadata.generation: workspace versionmetadata.resourceVersion: global workspace versionmetadata.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 allowedmetadata.generation: project versionmetadata.resourceVersion: global project versionmetadata.creationTimestamp: project creation date/timespec.description: project descriptionspec.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. Requiredname: 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. Requiredname: 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. Requiredname: 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 allowedmetadata.generation: notification channel versionmetadata.resourceVersion: global notification channel versionmetadata.creationTimestamp: notification channel creation date/timespec.type: notification channel type, allowed values: Email, Telegram, Webhook, Slack
Email notification channel parameters
spec.email.from: email address from which messages will be sentspec.email.smtp.address: mail server addressspec.email.smtp.auth.username: username for mail server authenticationspec.email.smtp.auth.password: password for mail server authenticationspec.email.stmp.requireTLS: flag indicating whether TLS is required when sending messages. Allowed values: true / falsespec.email.template: message template. Returned in responses, not modifiable via API
Telegram notification channel parameters
spec.telegram.apiUrl: Telegram API URL, by default the standardhttps://api.telegram.orgis usedspec.telegram.apiToken: authorization token for the Telegram channelspec.telegram.template: message template. Returned in responses, not modifiable via API
Slack notification channel parameters
spec.slack.apiURL: Slack URL for sending notificationsspec.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. Requiredproject_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. Requiredproject_name: project namename: 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. Requiredproject_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. Requiredproject_name: project namename: 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. Requiredproject_name: project namename: 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 allowedmetadata.generation: notification rule versionmetadata.resourceVersion: global notification rule versionmetadata.creationTimestamp: notification rule creation date/timespec.alert.selector.matchExpressions.items: array of notification selectors, described belowspec.notification.channel.name: notification channel namespec.notification.parameters: notification parameters, depend on the channel type, described belowspec.notification.repeatInterval: repeat notification interval, string value in the form ’30s’, ‘5m’, ‘1h’ (seconds, minutes, and hours are allowed)
Notification selector
key: label nameoperator: string operator designation, allowed values: Equal, NotEqual, Regex, NotRegexvalue: 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. Requiredproject_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. Requiredproject_name: project namename: 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. Requiredproject_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. Requiredproject_name: project namename: 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. Requiredproject_name: project namename: 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 versionmetadata.resourceVersion: global user versionmetadata.creationTimestamp: user creation date/timespec.email: user emailspec.firstName: user first namespec.lastName: user last namespec.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 versionmetadata.resourceVersion: global user versionmetadata.creationTimestamp: user creation date/timespec.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_adminspec.space: workspace the user role is bound tospec.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”.