title: "Custom API endpoints" description: "Generate read-only API endpoints that return aggregated server metrics. Plug into Grafana, scripts, or internal tooling." last_updated: "2026-05-24"

Custom API endpoints

Custom API endpoints expose read-only, scoped JSON for a subset of your servers and a subset of metrics. You pick the servers, you pick the metric fields, BoxWatch hands you a unique API key — then your scripts, Grafana data sources, and internal tooling can poll that endpoint without needing your full account credentials.

Think of it as a saved query you can hit from anywhere, with a key scoped only to that query.

Create an endpoint

1. Go to Dashboard → Custom Endpoints → New endpoint.
2. Name it (e.g. "Grafana prod CPU").
3. Pick Servers — the set of servers this endpoint can read.
4. Pick Metrics — the fields to return (e.g. cpu, memory, disk, network_rx).
5. Save. BoxWatch generates a unique api_key (prefix bw_api_<…>) and returns it once.

Copy the key immediately — you can re-create it later but the original key can't be recovered.

Call it

curl -H "Authorization: Bearer bw_api_YOUR_KEY" \
  https://api.boxwatch.app/endpoints/data

The response is JSON with the metric values for each server in the endpoint's scope. Exact shape depends on the metrics you selected:

{
  "endpoint": "Grafana prod CPU",
  "data": [
    {
      "server_id": 12,
      "hostname": "web-prod-1",
      "cpu": 23.4,
      "memory": 61.8,
      "disk": 47.2
    },
    {
      "server_id": 14,
      "hostname": "web-prod-2",
      "cpu": 19.1,
      "memory": 58.9,
      "disk": 51.0
    }
  ],
  "timestamp": "2026-05-24T03:14:22.418Z"
}

The endpoint key is scoped — it can read those servers and those metrics only. It can't list other servers, can't read alerts, can't change anything. Even if it leaks, the blast radius is the scope you chose.

Use cases

• Grafana data source — point the JSON datasource plugin at your endpoint URL with the bearer token, and you get BoxWatch metrics in Grafana panels.
• External status page — pull current values into a static site or a custom status renderer.
• Internal tooling — a Slack /server-status slash command, a Datadog custom check, a deployment script that refuses to ship while CPU > 80%.
• Read-only access for a vendor — share metrics with an outside contractor without giving them your account.

Rotating a key

There's no in-place rotation: delete the endpoint and create a new one with the same configuration. Update consumers to the new key.

The old key is invalidated immediately on delete.

Plan limits

Every plan gets at least one — Hobby users can plumb a single Grafana panel for free. The endpoint cap is independent of server caps, so an endpoint can include any combination of servers you already monitor.

API

Create body:

{
  "name": "Grafana prod CPU",
  "servers": [12, 14, 18],
  "metrics": ["cpu", "memory", "disk"]
}

(API reference pages are coming soon — see /docs/api for the overview.)

See also

• API keys — for full-scope account access (use sparingly)
• Server metrics
• TV dashboards — if you want a UI instead of a JSON consumer