Skip to content
Uptizm
Sign in
Menu
View as Markdown

API reference

Board

The widget board of the user a key acts as: its tiles and the values behind them.

GET /board board:read #

Get the 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

Response 200 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.

Code samples

curl -X GET "https://api.uptizm.com/v1/board" \
  -H "Authorization: Bearer $UPTIZM_API_KEY" \
  -H "Accept: application/json"
const response = await fetch('https://api.uptizm.com/v1/board', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.UPTIZM_API_KEY}`,
    'Accept': 'application/json',
  },
});

const data = await response.json();
<?php

$curl = curl_init('https://api.uptizm.com/v1/board');

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('UPTIZM_API_KEY'),
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
import os

import requests

response = requests.get(
    "https://api.uptizm.com/v1/board",
    headers={
        "Authorization": "Bearer " + os.environ["UPTIZM_API_KEY"],
        "Accept": "application/json",
    },
)

print(response.json())
PUT /board board:write #

Replace the 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.

Request body 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 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.

Code samples

curl -X PUT "https://api.uptizm.com/v1/board" \
  -H "Authorization: Bearer $UPTIZM_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [
        {
            "monitor_id": "00000000-0000-4000-8000-000000000000",
            "source": "status",
            "view": "card",
            "size": "s",
            "range": "24h"
        }
    ]
}'
const payload = {
    "widgets": [
        {
            "monitor_id": "00000000-0000-4000-8000-000000000000",
            "source": "status",
            "view": "card",
            "size": "s",
            "range": "24h"
        }
    ]
};

const response = await fetch('https://api.uptizm.com/v1/board', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.UPTIZM_API_KEY}`,
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
<?php

$curl = curl_init('https://api.uptizm.com/v1/board');

$payload = <<<'JSON'
{
    "widgets": [
        {
            "monitor_id": "00000000-0000-4000-8000-000000000000",
            "source": "status",
            "view": "card",
            "size": "s",
            "range": "24h"
        }
    ]
}
JSON;

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('UPTIZM_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($curl);
import os

import requests

response = requests.put(
    "https://api.uptizm.com/v1/board",
    headers={
        "Authorization": "Bearer " + os.environ["UPTIZM_API_KEY"],
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    data=r'''{
    "widgets": [
        {
            "monitor_id": "00000000-0000-4000-8000-000000000000",
            "source": "status",
            "view": "card",
            "size": "s",
            "range": "24h"
        }
    ]
}''',
)

print(response.json())
GET /board/data board:read #

Get the board's values

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.

Parameters

NameInTypeRequiredDescription
widgetsquerystringNoComma-separated widget ids, at most 20; every widget of the board when omitted.

Response 200 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.

Code samples

curl -X GET "https://api.uptizm.com/v1/board/data" \
  -H "Authorization: Bearer $UPTIZM_API_KEY" \
  -H "Accept: application/json"
const response = await fetch('https://api.uptizm.com/v1/board/data', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.UPTIZM_API_KEY}`,
    'Accept': 'application/json',
  },
});

const data = await response.json();
<?php

$curl = curl_init('https://api.uptizm.com/v1/board/data');

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('UPTIZM_API_KEY'),
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
import os

import requests

response = requests.get(
    "https://api.uptizm.com/v1/board/data",
    headers={
        "Authorization": "Bearer " + os.environ["UPTIZM_API_KEY"],
        "Accept": "application/json",
    },
)

print(response.json())

Type to search the guides, resources and endpoints.