The REST API

Every page in the dashboard reads from an HTTP API, and the readable part of it is open to API keys. The API describes itself. Ask the install, and it answers with every endpoint, what each one returns, what it takes, and what it leads to.

API keys

Open the user menu and choose API, then + New key. Say what the key is for, and tick Let this key write as well as read if it needs to. The key is shown once. Copy it then, because only a hash of it is stored. Keys look like ok_…, never expire, and are revoked from the same page.

• A key sees exactly what its owner sees, resolved on every request. If the owner's access is narrowed, so is the key's. A key can be cut down further, to chosen applications, services or machines.
• A key belongs to the organisation it was made in.
• Making keys needs the API keys capability, which is off by default for members. Viewers never get it. If the capability is taken away, the keys a person already made stop seeing anything.

View and write

• View keys can only GET. Everything in the catalogue is readable.
• Write keys can also do what automation needs: close a problem, run a scan, create and run synthetic checks, pin a function, instrument a unit, mark an error group, refresh the security inventory.

Some things no key can do, whatever its scope. Identity, configuration and deletion are done by a person signed in to the dashboard. That covers accounts, keys themselves, organisations, teams and invitations, the sign-in book, the console, load tests, rotating application and agent keys, deleting applications or hosts, and editing workflows. The catalogue lists these refusals itself, so a program learns its limits from the document rather than from a 403.

The catalogue

curl -H "Authorization: Bearer ok_…" https://your-install/api

/api and /api/v1 return the catalogue as JSON. Every answer to a key also carries Link: </api>; rel="service-desc". The endpoints are grouped:

• applications and real users;
• synthetic monitoring;
• infrastructure;
• IoT devices;
• integrations;
• services and traces;
• promises and journeys: SLOs, trends, funnels, databases and deploys;
• problems;
• security.

Each endpoint has leads_to, the next step down. An application leads to its sessions, a session to its views and backend calls, a call to its service, a service to its process, and a process to its host. A program can start at the root and walk to the thing that is wrong, without being told the shape in advance.

Conventions

• Authentication is Authorization: Bearer <key>, never a query string. A request without a key gets 401, with a hint.
• Every timestamp is epoch milliseconds, UTC.
• Most lists take ?range= (1h, 6h, 24h, 7d, 30d, 90d) or ?from=&to= in epoch ms. Open problems ignore the range on purpose.
• A missing measurement is null, never 0. A zero means it was measured and was zero.
• Sessions and views from your own synthetic checks carry synthetic=1.
• Visitor IP addresses are not stored. A country and a salted hash are.

A worked example

Find out what is wrong, and follow it down to a trace:

KEY="Authorization: Bearer ok_…"
BASE=https://your-install

# 1. What is open right now?
curl -s -H "$KEY" "$BASE/api/problems?status=open"

# 2. One problem: its evidence, its root cause and what it affects
curl -s -H "$KEY" "$BASE/api/problems/1234"

# 3. The service it is about, over the last six hours
curl -s -H "$KEY" "$BASE/api/services/<serviceId>?range=6h"

# 4. The slow calls of that service, then one of them span by span
curl -s -H "$KEY" "$BASE/api/traces?service=<serviceId>&slow=1&range=6h"
curl -s -H "$KEY" "$BASE/api/traces/<traceId>"

The same walk works from the visitor's side: /api/apps, then /api/apps/{id}/overview, then /api/apps/{id}/sessions, then one session with every backend call it caused. With a write key, close the ticket when it is fixed:

curl -s -X POST -H "$KEY" "$BASE/api/problems/1234/close"

Deploy markers

Let CI tell the install when it deploys. Charts draw the marker, and a ticket that opens within half an hour of a deploy ranks the deploy first among its causes.

curl -s -X POST https://your-install/api/deploy \
  -H 'Content-Type: application/json' \
  -d '{"key":"rum_…","version":"2026.10.26-1","note":"checkout rewrite"}'

The key here is the application key, the one in the tag. The version can be up to 80 characters and the note up to 200. Read markers back with /api/apps/{id}/deploys.

Installing from a program

/api/install/bootstrap returns the tag for an application and the one-line command for a machine, built for this install's address. With create=1 it creates the application when the name is new. It hands out an agent key, so it needs a write key.

Sending data in

The API above is for reading. Data arrives at the collector endpoints: /collect (the browser tag), /collect/backend (the server agent), /collect/iot (devices) and /v1/traces (OpenTelemetry).