# Board API

The Uptizm API has 3 endpoints on this resource, one section each.

## Get the board

`GET /board`

The widgets of the board a key acts on, the board of the member who created the key in the key's team, in display order. A widget whose monitor was deleted is left out. Read the Build a board guide first: https://uptizm.com/docs/build-a-board.md

- URL: `https://api.uptizm.com/v1/board`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `board:read`
- Tag: Board
- operationId: `v1.board.show`

### Response 200

Content type: `application/json`.

- `data` (array of BoardWidgetResource, required)
  - `id` (string, required)
  - `monitor_id` (string, required)
  - `monitor_metric_id` (string or null, required)
  - `source` (string, one of `"status"`, `"response_time"`, `"uptime"`, `"metric"`, required)
  - `view` (string, one of `"card"`, `"chart"`, `"list"`, required)
  - `size` (string, one of `"s"`, `"m"`, `"l"`, required)
  - `range` (string, required)
  - `position` (integer, required)
  - `monitor` (object, required)
    - `id` (string, required)
    - `name` (string, required)
  - `metric` (object or null, required)
    - `id` (string, required)
    - `key` (string, required)
    - `label` (string, required)
    - `unit` (string or null, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"`, `null`, required)
    - `type` (string, one of `"numeric"`, `"status"`, `"string"`, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: An error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Replace the board

`PUT /board`

Replaces the whole widget list with `widgets`, in the order sent, and returns the stored list. At most 20 widgets; an empty list clears the board. The server mints every widget id on each save and never trusts one sent by the client. An unknown, foreign or deleted monitor, a metric outside its widget's monitor, or a view the source cannot render answers 422 and stores nothing. Allows 30 saves a minute per key, on top of the key's write budget.

- URL: `https://api.uptizm.com/v1/board`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `board:write`
- Tag: Board
- operationId: `v1.board.replace`

### Request body

Content type: `application/json`.

- `widgets` (array of object, max items 20, required)
  - `monitor_id` (string, uuid, required)
  - `monitor_metric_id` (string or null, uuid)
  - `source` (BoardWidgetSource: string, one of `"status"`, `"response_time"`, `"uptime"`, `"metric"`, required): The signal a board widget reads.
  - `view` (BoardWidgetView: string, one of `"card"`, `"chart"`, `"list"`, required): How a board widget renders its signal: a single value, a time series or the newest rows.
  - `size` (BoardWidgetSize: string, one of `"s"`, `"m"`, `"l"`, required): Grid footprint of a board widget tile.
  - `range` (string, one of `"24h"`, `"7d"`, `"30d"`, `"90d"`, required)

### Response 200

Content type: `application/json`.

- `data` (array of BoardWidgetResource, required)
  - `id` (string, required)
  - `monitor_id` (string, required)
  - `monitor_metric_id` (string or null, required)
  - `source` (string, one of `"status"`, `"response_time"`, `"uptime"`, `"metric"`, required)
  - `view` (string, one of `"card"`, `"chart"`, `"list"`, required)
  - `size` (string, one of `"s"`, `"m"`, `"l"`, required)
  - `range` (string, required)
  - `position` (integer, required)
  - `monitor` (object, required)
    - `id` (string, required)
    - `name` (string, required)
  - `metric` (object or null, required)
    - `id` (string, required)
    - `key` (string, required)
    - `label` (string, required)
    - `unit` (string or null, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"`, `null`, required)
    - `type` (string, one of `"numeric"`, `"status"`, `"string"`, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Get the board's values

`GET /board/data`

The live values behind the widgets, keyed by widget id. `widgets` is a comma-separated list of up to 20 widget ids; without it every widget is read. An id that is not on the board is absent from the answer rather than refused. Each entry carries the monitor's state and the one block its source and view fill (`uptime`, `latest`, `points` or `rows`), the others null; the Build a board guide lists every field: https://uptizm.com/docs/build-a-board.md. Allows 120 reads a minute per key, on top of the key's read budget.

- URL: `https://api.uptizm.com/v1/board/data`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `board:read`
- Tag: Board
- operationId: `v1.board.data`

### Parameters

- `widgets` (query, string): Comma-separated widget ids, at most 20; every widget of the board when omitted.

### Response 200

Content type: `application/json`.

- `data` (object, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md
