Skip to content

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)Required
  • namestringRequired
  • presetstringRequired

    Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

  • endpointstringRequired
  • temporalitystringRequired

    Possible valuescumulativedelta

  • signalsarray of stringsRequired

    Each is one ofmetricsevents

  • enabledbooleanRequired
  • headersarray of objectsRequired

    The 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
    • namestringRequired
    • hintstringRequired
  • createdAtstring (date-time)Required
  • statusstringRequired

    waiting has not been sent to yet; retrying is failing and being tried again on its schedule.

    Possible valuesoffwaitingokretrying

  • lastOkAtstring (date-time)RequiredNullable
  • lastReasonstringRequiredNullable

    While retrying, a fixed code for why the last send failed (dns, blocked, tls, timeout, connect, too_large, headers, status_4xx, status_5xx and so on), never text from the other end.

  • lastStatusintegerRequiredNullable
  • failingSincestring (date-time)RequiredNullable

List all monitoring presets

PermissionScreens · Read

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 objectsRequired
    Show child attributesHide child attributes
    • idstringRequired
    • labelstringRequired
    • temporalitystringRequired

      Possible valuescumulativedelta

    • headerstringOptional
    • headerHelpstringOptional
    • sitesarray of objectsRequired
      Show child attributesHide child attributes
      • idstringRequired
      • labelstringRequired
      • endpointstringRequired
      • unconfirmedbooleanOptional
    • endpointHelpstringOptional
    • signalsarray of stringsRequired

      Each is one ofmetricsevents

    • eventsAvailablebooleanRequired
  • maxDestinationsintegerRequired

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

List all monitoring destinations

PermissionScreens · Read

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 objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • presetstringRequired

      Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

    • endpointstringRequired
    • temporalitystringRequired

      Possible valuescumulativedelta

    • signalsarray of stringsRequired

      Each is one ofmetricsevents

    • enabledbooleanRequired
    • headersarray of objectsRequired

      The 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
      • namestringRequired
      • hintstringRequired
    • createdAtstring (date-time)Required
    • statusstringRequired

      waiting has not been sent to yet; retrying is failing and being tried again on its schedule.

      Possible valuesoffwaitingokretrying

    • lastOkAtstring (date-time)RequiredNullable
    • lastReasonstringRequiredNullable

      While retrying, a fixed code for why the last send failed (dns, blocked, tls, timeout, connect, too_large, headers, status_4xx, status_5xx and so on), never text from the other end.

    • lastStatusintegerRequiredNullable
    • failingSincestring (date-time)RequiredNullable

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

501not_available

not_available: monitoring destinations are not set up on this server.

Add a monitoring destination

PermissionSettings · Write

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

  • idempotencyKeystringOptional

    Optional. Send the same value on a retry and nothing is made twice: the repeat answers 200 with the destination already made.

  • namestringRequired
  • presetstringRequired

    Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

  • endpointstringRequired

    The base URL; /v1/metrics and /v1/logs are added.

  • temporalitystringOptional

    The preset’s when left out.

    Possible valuescumulativedelta

  • signalsarray of stringsOptional

    The preset’s when left out.

    Each is one ofmetricsevents

  • headersobjectOptional

    At most 20, 8 KB in all. Sealed; never returned.

Returns

Added.

An object with:

  • destinationobjectRequired

    A monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.

    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • presetstringRequired

      Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

    • endpointstringRequired
    • temporalitystringRequired

      Possible valuescumulativedelta

    • signalsarray of stringsRequired

      Each is one ofmetricsevents

    • enabledbooleanRequired
    • headersarray of objectsRequired

      The 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
      • namestringRequired
      • hintstringRequired
    • createdAtstring (date-time)Required
    • statusstringRequired

      waiting has not been sent to yet; retrying is failing and being tried again on its schedule.

      Possible valuesoffwaitingokretrying

    • lastOkAtstring (date-time)RequiredNullable
    • lastReasonstringRequiredNullable

      While retrying, a fixed code for why the last send failed (dns, blocked, tls, timeout, connect, too_large, headers, status_4xx, status_5xx and so on), never text from the other end.

    • lastStatusintegerRequiredNullable
    • failingSincestring (date-time)RequiredNullable

Errors

StatusCodeMeaning
400own_host

A field was refused, with field and code (for example the field endpoint and the code own_host); never the value sent.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

409not_connectedapi_off

limit (5 destinations), not_connected (Mestra screens are off) or api_off.

413

The body is over 16 KB.

Retrieve a monitoring destination

PermissionScreens · Read

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:

  • destinationobjectRequired

    A monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.

    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • presetstringRequired

      Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

    • endpointstringRequired
    • temporalitystringRequired

      Possible valuescumulativedelta

    • signalsarray of stringsRequired

      Each is one ofmetricsevents

    • enabledbooleanRequired
    • headersarray of objectsRequired

      The 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
      • namestringRequired
      • hintstringRequired
    • createdAtstring (date-time)Required
    • statusstringRequired

      waiting has not been sent to yet; retrying is failing and being tried again on its schedule.

      Possible valuesoffwaitingokretrying

    • lastOkAtstring (date-time)RequiredNullable
    • lastReasonstringRequiredNullable

      While retrying, a fixed code for why the last send failed (dns, blocked, tls, timeout, connect, too_large, headers, status_4xx, status_5xx and so on), never text from the other end.

    • lastStatusintegerRequiredNullable
    • failingSincestring (date-time)RequiredNullable

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: no such destination in this organisation (another organisation’s is as unknown as a missing one).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

Update a monitoring destination

PermissionSettings · Write

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

  • namestringOptional
  • endpointstringOptional
  • temporalitystringOptional

    Possible valuescumulativedelta

  • signalsarray of stringsOptional

    Each is one ofmetricsevents

  • enabledbooleanOptional
  • headersobjectOptional

Returns

Changed.

An object with:

  • destinationobjectRequired

    A monitoring destination: where the organisation’s screen telemetry is sent. Header values are never shown.

    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • presetstringRequired

      Possible valuesdatadognewrelichoneycombgrafanacloudelasticcustom

    • endpointstringRequired
    • temporalitystringRequired

      Possible valuescumulativedelta

    • signalsarray of stringsRequired

      Each is one ofmetricsevents

    • enabledbooleanRequired
    • headersarray of objectsRequired

      The 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
      • namestringRequired
      • hintstringRequired
    • createdAtstring (date-time)Required
    • statusstringRequired

      waiting has not been sent to yet; retrying is failing and being tried again on its schedule.

      Possible valuesoffwaitingokretrying

    • lastOkAtstring (date-time)RequiredNullable
    • lastReasonstringRequiredNullable

      While retrying, a fixed code for why the last send failed (dns, blocked, tls, timeout, connect, too_large, headers, status_4xx, status_5xx and so on), never text from the other end.

    • lastStatusintegerRequiredNullable
    • failingSincestring (date-time)RequiredNullable

Errors

StatusCodeMeaning
400own_hosttoo_large

Nothing to change, or a field was refused (a field and a code such as own_host or too_large).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: no such destination in this organisation (another organisation’s is as unknown as a missing one).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

413

The body is over 16 KB.

Delete a monitoring destination

PermissionSettings · Write

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: no such destination in this organisation (another organisation’s is as unknown as a missing one).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

Test a monitoring destination

PermissionScreens · Read

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:

  • okbooleanRequired
  • statusintegerRequiredNullable
  • reasonstringRequiredNullable

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: no such destination in this organisation (another organisation’s is as unknown as a missing one).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

429too_many

too_many: one test per organisation every 10 seconds; see Retry-After.

List all telemetry keys

PermissionSettings · Read

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 objectsRequired
    Show child attributesHide child attributes
    • idstring (uuid)Required
    • namestringRequired
    • hintstringRequired

      The last 4 characters of the key.

    • createdAtstring (date-time)Required
    • lastUsedAtstring (date-time)RequiredNullable

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

501not_available

not_available: telemetry keys are not set up on this server.

Create a telemetry key

PermissionSettings · Write

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

  • idempotencyKeystringOptional

    Optional. Send the same value on a retry and no second key is made: the repeat answers 200 with the key already made and token null (it was shown once).

  • namestringRequired

Returns

Made. token is shown this once.

An object with:

  • keyobjectRequired

    A 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)Required
    • namestringRequired
    • hintstringRequired

      The last 4 characters of the key.

    • createdAtstring (date-time)Required
    • lastUsedAtstring (date-time)RequiredNullable
  • tokenstringRequiredNullable

    The key, mtk_ and 43 characters. Shown once; null on a repeat of a create.

Errors

StatusCodeMeaning
400

The name was refused: the answer names the field and why.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

409not_connectedapi_off

limit (10 keys), not_connected or api_off.

413

The body is over 16 KB.

Delete a telemetry key

PermissionSettings · Write

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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

403 for a role below the route’s minimum (“Your role (<role>) can’t <action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code wrong_key with “This key needs the <Area> · <Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can’t do that.” for a call only the Mestra apps make.

404not_found

not_found: no such key in this organisation (another organisation’s is as unknown as a missing one).

409api_off

409 with code api_off (“Turn on the API in Developer → API and MCP first.”): an owner hasn’t turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.