# Build a board

A board is a grid of up to 20 tiles, each showing one signal of one monitor: its status, its response time, its uptime or one of its custom metrics. Every person has their own board in each team. A key acts on the board of the team member who created it, in the key's team, so what a key saves is the board that person sees in the app. To build a board for someone else, have them create the key.

## Abilities

`GET /board` and `GET /board/data` need `board:read`, which the read only, read and write, and full presets carry. `PUT /board` needs `board:write`, which the read and write and full presets carry. Anonymous workspace keys carry neither. A key keeps the abilities it was created with, so a key made before the board joined the API has neither: create a new key, or a custom one with the board abilities. [Authentication](https://uptizm.com/docs/authentication.md) covers the presets.

## Read the board

`GET /board` returns the widgets in display order:

```json
{
  "data": [
    {
      "id": "9d4c2f8a-5b1e-4c7d-8e2f-1a3b5c7d9e0f",
      "monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "monitor_metric_id": null,
      "source": "response_time",
      "view": "chart",
      "size": "m",
      "range": "24h",
      "position": 0,
      "monitor": {
        "id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
        "name": "Checkout API"
      },
      "metric": null
    }
  ]
}
```

A widget whose monitor was deleted is left out. `metric` is filled for a metric widget, with the metric's `id`, `key`, `label`, `unit` and `type`.

## Widget fields

- `monitor_id` is one of the team's monitors.
- `source` is the signal: `status`, `response_time`, `uptime` or `metric`.
- `monitor_metric_id` is a custom metric of that same monitor. A `metric` widget requires it; every other source must leave it out or send null.
- `view` is how the tile renders it: `card` (one value), `chart` (a series) or `list` (the newest rows). `status` and `uptime` render as `card` only; `response_time` and `metric` render as any of the three. A chart of a metric needs a `numeric` metric, because a text or status reading has no number to plot.
- `size` is the tile's footprint: `s`, `m` or `l`.
- `range` is the window the tile reads: `24h`, `7d`, `30d` or `90d`.

## Save the board

`PUT /board` replaces the whole list. Send every widget you want to keep, in the order to show them; the array index becomes `position`. An empty `widgets` list clears the board.

```json
{
  "widgets": [
    {
      "monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "source": "status",
      "view": "card",
      "size": "s",
      "range": "24h"
    },
    {
      "monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "source": "uptime",
      "view": "card",
      "size": "s",
      "range": "30d"
    },
    {
      "monitor_id": "9d4c2f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "monitor_metric_id": "9d4c2f81-6b7c-4d8e-9f0a-1b2c3d4e5f60",
      "source": "metric",
      "view": "chart",
      "size": "l",
      "range": "7d"
    }
  ]
}
```

The answer is the stored list, in the shape of `GET /board`. The server mints a new id for every widget on every save, so an id from an earlier read is not kept and an `id` you send is ignored. Read the ids from the answer before you ask for values.

A 422 stores nothing. It answers when:

- the list holds more than 20 widgets;
- a field is missing or holds a value outside the lists above;
- a monitor is unknown, belongs to another team or was deleted;
- a metric does not belong to its widget's monitor;
- the view is one the source cannot render, or a chart names a metric that is not `numeric`.

An unknown monitor and another team's monitor get the same answer.

## Read the values

`GET /board/data` returns the live values behind the tiles, keyed by widget id. Name the widgets in `widgets`, a comma-separated list of up to 20 ids (`GET /board/data?widgets=<id>,<id>`), or leave it out to read every widget. An id that is not on the board is left out of the answer rather than refused.

```json
{
  "data": {
    "9d4c2f8a-5b1e-4c7d-8e2f-1a3b5c7d9e0f": {
      "monitor": {
        "status": "active",
        "last_status": "up",
        "last_checked_at": "2026-11-17T09:59:30+00:00",
        "last_response_ms": 182,
        "interval_sec": 60
      },
      "uptime": null,
      "latest": null,
      "points": [
        {
          "recorded_at": "2026-11-17T09:00:00+00:00",
          "numeric_value": 190,
          "band": null
        },
        {
          "recorded_at": "2026-11-17T09:59:30+00:00",
          "numeric_value": 182,
          "band": null
        }
      ],
      "rows": null
    }
  }
}
```

Every entry carries `monitor`: its switch (`status`, `active` or `paused`), its last reading (`last_status`, `last_checked_at`, `last_response_ms`) and `interval_sec`, the check interval the plan allows. A reading older than twice `interval_sec` is stale. Of the other four blocks, the widget's source and view fill one and the rest are null:

- `uptime` for an `uptime` card: `range`, `total`, `up`, `down`, `degraded` and `uptime_ratio` (a fraction, `0.9921` is 99.21%). It is null when the range holds no reading.
- `latest` for a `metric` card: the metric's newest reading in the range (`recorded_at`, `numeric_value`, `string_value`, `status_value`, `band`), or null when there is none.
- `points` for a chart, oldest first, at most 120 points. A longer series is thinned at an even stride and keeps its first and last point. A response time point is a bucket median in milliseconds with `band` null. A metric point is one reading over `24h`; over a longer range it is a bucket average with the worst band in the bucket.
- `rows` for a list, newest first, at most 10. A response time row has `recorded_at`, `status`, `status_code` and `numeric_value` (the response time in milliseconds); a metric row has the same fields as `latest`.

A `status` card and a `response_time` card read only `monitor`, so every other block is null.

## How often to poll

A monitor takes a new reading once per `interval_sec`, so polling faster shows nothing new. The Uptizm app reads one widget at most once every 15 seconds, and a chart over 7 to 90 days at most once every 10 minutes, since one reading barely moves such a series. Poll at the same pace, and name only the widgets you need in `widgets`.

## Limits

`PUT /board` allows 30 saves a minute and `GET /board/data` 120 reads a minute, per key. Both count against the key's own budget as well; [Rate limits](https://uptizm.com/docs/rate-limits.md) has the numbers. On a 429, wait the `Retry-After` seconds.
