API reference
Monitoring
Monitoring sends the organisation’s own screen telemetry (OpenTelemetry metrics and events) to places it chooses, such as Datadog, New Relic, Honeycomb, Grafana Cloud, Elastic or any OTLP/HTTP endpoint. A destination holds the vendor’s key, sealed: it is never shown again. A telemetry read key lets the organisation’s own Prometheus, Grafana Alloy or monitoring agent pull the same metrics from /api/v1/telemetry/metrics. The read key starts mtk_ and is sent as Authorization: Bearer mtk_…. It is not an API key: it reads this one organisation’s screen telemetry and opens no other route. The answer is OpenMetrics text, at most 60 seconds old, so the route works as a scrape target for Prometheus or Alloy. Seeing and testing destinations and the presets: an editor or an owner, with Screens · Read. Changing destinations and every telemetry key route: an owner, with Settings. See Monitoring for the guide.
The Monitoring destination object
A monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.
Attributes
idstring (uuid)RequirednamestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredtemporalitystringRequiredPossible values
cumulativedeltasignalsarray of stringsRequiredEach is one of
metricseventsenabledbooleanRequiredheadersarray of objectsRequiredThe headers set, by name, with the last 4 characters of each value (empty for a short one). Never a value.
Show child attributesHide child attributes
namestringRequiredhintstringRequired
createdAtstring (date-time)RequiredstatusstringRequiredwaitinghas not been sent to yet;retryingis failing and being tried again on its schedule.Possible values
offwaitingokretryinglastOkAtstring (date-time)RequiredNullablelastReasonstringRequiredNullableWhile retrying, a fixed code for why the last send failed (
dns,blocked,tls,timeout,connect,too_large,headers,status_4xx,status_5xxand so on), never text from the other end.lastStatusintegerRequiredNullablefailingSincestring (date-time)RequiredNullable
List all monitoring presets
Needs an editor’s or an owner’s key or session (a viewer is refused). Returns the vendors a monitoring destination can be set up for (Datadog, New Relic, Honeycomb, Grafana Cloud, Elastic, or any OTLP/HTTP endpoint): each one’s regions, the header its key goes in, and the metric temporality it wants, with the most destinations an organisation may have.
Returns
The presets.
An object with:
presetsarray of objectsRequiredShow child attributesHide child attributes
idstringRequiredlabelstringRequiredtemporalitystringRequiredPossible values
cumulativedeltaheaderstringOptionalheaderHelpstringOptionalsitesarray of objectsRequiredShow child attributesHide child attributes
idstringRequiredlabelstringRequiredendpointstringRequiredunconfirmedbooleanOptional
endpointHelpstringOptionalsignalsarray of stringsRequiredEach is one of
metricseventseventsAvailablebooleanRequired
maxDestinationsintegerRequired
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_off |
|
List all monitoring destinations
Needs an editor’s or an owner’s key or session (a viewer is refused). Returns the organisation’s monitoring destinations: where its screen telemetry is sent. Each shows its status and which headers are set, with the last 4 characters of each value. A value is never shown.
Returns
The destinations, oldest first.
An object with:
destinationsarray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredtemporalitystringRequiredPossible values
cumulativedeltasignalsarray of stringsRequiredEach is one of
metricseventsenabledbooleanRequiredheadersarray of objectsRequiredThe headers set, by name, with the last 4 characters of each value (empty for a short one). Never a value.
Show child attributesHide child attributes
namestringRequiredhintstringRequired
createdAtstring (date-time)RequiredstatusstringRequiredwaitinghas not been sent to yet;retryingis failing and being tried again on its schedule.Possible values
offwaitingokretryinglastOkAtstring (date-time)RequiredNullablelastReasonstringRequiredNullableWhile retrying, a fixed code for why the last send failed (
dns,blocked,tls,timeout,connect,too_large,headers,status_4xx,status_5xxand so on), never text from the other end.lastStatusintegerRequiredNullablefailingSincestring (date-time)RequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_off |
|
501 | not_available |
|
Add a monitoring destination
Needs an owner’s key or session. Adds a destination that the organisation’s screen telemetry (OpenTelemetry metrics and events) is sent to. The headers hold the vendor’s key and are sealed: they are never returned. An organisation may have 5. Needs Mestra screens turned on.
Body parameters
idempotencyKeystringOptionalOptional. Send the same value on a retry and nothing is made twice: the repeat answers 200 with the destination already made.
namestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredThe base URL; /v1/metrics and /v1/logs are added.
temporalitystringOptionalThe preset’s when left out.
Possible values
cumulativedeltasignalsarray of stringsOptionalThe preset’s when left out.
Each is one of
metricseventsheadersobjectOptionalAt most 20, 8 KB in all. Sealed; never returned.
Returns
Added.
An object with:
destinationobjectRequiredA monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.
Show child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredtemporalitystringRequiredPossible values
cumulativedeltasignalsarray of stringsRequiredEach is one of
metricseventsenabledbooleanRequiredheadersarray of objectsRequiredThe headers set, by name, with the last 4 characters of each value (empty for a short one). Never a value.
Show child attributesHide child attributes
namestringRequiredhintstringRequired
createdAtstring (date-time)RequiredstatusstringRequiredwaitinghas not been sent to yet;retryingis failing and being tried again on its schedule.Possible values
offwaitingokretryinglastOkAtstring (date-time)RequiredNullablelastReasonstringRequiredNullableWhile retrying, a fixed code for why the last send failed (
dns,blocked,tls,timeout,connect,too_large,headers,status_4xx,status_5xxand so on), never text from the other end.lastStatusintegerRequiredNullablefailingSincestring (date-time)RequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
400 | own_host | A field was refused, with |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | not_connectedapi_off |
|
413 | The body is over 16 KB. |
Retrieve a monitoring destination
Needs an editor’s or an owner’s key or session (a viewer is refused). Returns one destination: its status, when it last worked, why it last failed (a fixed code) and since when it has been failing.
Path parameters
idstring (uuid)Required
Returns
The destination.
An object with:
destinationobjectRequiredA monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.
Show child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredtemporalitystringRequiredPossible values
cumulativedeltasignalsarray of stringsRequiredEach is one of
metricseventsenabledbooleanRequiredheadersarray of objectsRequiredThe headers set, by name, with the last 4 characters of each value (empty for a short one). Never a value.
Show child attributesHide child attributes
namestringRequiredhintstringRequired
createdAtstring (date-time)RequiredstatusstringRequiredwaitinghas not been sent to yet;retryingis failing and being tried again on its schedule.Possible values
offwaitingokretryinglastOkAtstring (date-time)RequiredNullablelastReasonstringRequiredNullableWhile retrying, a fixed code for why the last send failed (
dns,blocked,tls,timeout,connect,too_large,headers,status_4xx,status_5xxand so on), never text from the other end.lastStatusintegerRequiredNullablefailingSincestring (date-time)RequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_found |
|
409 | api_off |
|
Update a monitoring destination
Needs an owner’s key or session. Changes a destination’s name, endpoint, signals, temporality, whether it is on, or its headers (the whole set is replaced). Moving the endpoint to another host without sending headers drops the stored key. Editing starts it afresh: its failing state is cleared.
Path parameters
idstring (uuid)Required
Body parameters
namestringOptionalendpointstringOptionaltemporalitystringOptionalPossible values
cumulativedeltasignalsarray of stringsOptionalEach is one of
metricseventsenabledbooleanOptionalheadersobjectOptional
Returns
Changed.
An object with:
destinationobjectRequiredA monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.
Show child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredpresetstringRequiredPossible values
datadognewrelichoneycombgrafanacloudelasticcustomendpointstringRequiredtemporalitystringRequiredPossible values
cumulativedeltasignalsarray of stringsRequiredEach is one of
metricseventsenabledbooleanRequiredheadersarray of objectsRequiredThe headers set, by name, with the last 4 characters of each value (empty for a short one). Never a value.
Show child attributesHide child attributes
namestringRequiredhintstringRequired
createdAtstring (date-time)RequiredstatusstringRequiredwaitinghas not been sent to yet;retryingis failing and being tried again on its schedule.Possible values
offwaitingokretryinglastOkAtstring (date-time)RequiredNullablelastReasonstringRequiredNullableWhile retrying, a fixed code for why the last send failed (
dns,blocked,tls,timeout,connect,too_large,headers,status_4xx,status_5xxand so on), never text from the other end.lastStatusintegerRequiredNullablefailingSincestring (date-time)RequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
400 | own_hosttoo_large | Nothing to change, or a field was refused (a |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_found |
|
409 | api_off |
|
413 | The body is over 16 KB. |
Delete a monitoring destination
Needs an owner’s key or session. Deletes a destination and forgets its key and its place: nothing more is sent to it.
Path parameters
idstring (uuid)Required
Returns
Removed.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_found |
|
409 | api_off |
|
Test a monitoring destination
Needs an editor’s or an owner’s key or session (a viewer is refused). Sends one small test (a metric mestra.test of 1 and a log Mestra test, for the signals the destination carries) the way real telemetry is sent, and says whether it got through: ok, the HTTP status if one came back, and a fixed reason code when it did not. It never repeats what the other end said. One test per organisation every 10 seconds.
Path parameters
idstring (uuid)Required
Returns
The result of the test.
An object with:
okbooleanRequiredstatusintegerRequiredNullablereasonstringRequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_found |
|
409 | api_off |
|
429 | too_many |
|
List all telemetry keys
Needs an owner’s key or session, even though it only reads. Returns the organisation’s telemetry read keys: the keys that read its screen telemetry from /api/v1/telemetry/metrics. A key is shown only when it is made; the list has each one’s name, last 4 characters and last use.
Returns
The keys, oldest first.
An object with:
keysarray of objectsRequiredShow child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredhintstringRequiredThe last 4 characters of the key.
createdAtstring (date-time)RequiredlastUsedAtstring (date-time)RequiredNullable
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | api_off |
|
501 | not_available |
|
Create a telemetry key
Needs an owner’s key or session. Makes a telemetry read key (mtk_…). The answer is the only time the key is shown. It reads this organisation’s screen telemetry and opens no other route. An organisation may have 10.
Body parameters
idempotencyKeystringOptionalOptional. Send the same value on a retry and no second key is made: the repeat answers 200 with the key already made and
tokennull (it was shown once).namestringRequired
Returns
Made. token is shown this once.
An object with:
keyobjectRequiredA telemetry read key: the credential for
/api/v1/telemetry/metrics. The key itself is shown once, when it is made.Show child attributesHide child attributes
idstring (uuid)RequirednamestringRequiredhintstringRequiredThe last 4 characters of the key.
createdAtstring (date-time)RequiredlastUsedAtstring (date-time)RequiredNullable
tokenstringRequiredNullableThe key,
mtk_and 43 characters. Shown once; null on a repeat of a create.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The name was refused: the answer names the | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
409 | not_connectedapi_off |
|
413 | The body is over 16 KB. |
Delete a telemetry key
Needs an owner’s key or session. Revokes a telemetry read key: it stops working at once.
Path parameters
idstring (uuid)Required
Returns
Revoked.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_found |
|
409 | api_off |
|