Your first API call

Three calls take you from a new token to a Monitor’s uptime. Each is shown in curl, in JavaScript (fetch, in Node 18 or later) and in Python (its standard library alone). Pick a language once, and the page keeps it.

Before you start

Make an API token and copy it. Then put it in the UUP_API_TOKEN environment variable, where every example reads it:

export UUP_API_TOKEN="uup_api_…"

Keep the token out of your code and out of anything you commit. Anyone who has it can do what it allows.

1. List your Projects

Everything in the API lives under a Project, so start by finding yours. This lists the Projects your token reaches:

curl

curl -H "Authorization: Bearer $UUP_API_TOKEN" \
  "https://api.uup.dev/v1/projects"

JavaScript

const response = await fetch("https://api.uup.dev/v1/projects", {
  headers: { Authorization: `Bearer ${process.env.UUP_API_TOKEN}` },
});
console.log(await response.json());

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.uup.dev/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['UUP_API_TOKEN']}"},
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

Each Project in data has an id, such as prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8. Copy the one you want.

2. List the Project’s Monitors

Put that id in the path:

curl

curl -H "Authorization: Bearer $UUP_API_TOKEN" \
  "https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors"

JavaScript

const response = await fetch("https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors", {
  headers: { Authorization: `Bearer ${process.env.UUP_API_TOKEN}` },
});
console.log(await response.json());

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors",
    headers={"Authorization": f"Bearer {os.environ['UUP_API_TOKEN']}"},
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

Each Monitor comes with its id, its status and its Checks. A long list comes a page at a time: How requests work says how to ask for the next one.

3. Read one Monitor’s uptime

Put a Monitor’s id, such as mon_01J9Z3K8X4M2N6P8Q0R2S4T6V8, after the Project’s:

curl

curl -H "Authorization: Bearer $UUP_API_TOKEN" \
  "https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors/mon_01J9Z3K8X4M2N6P8Q0R2S4T6V8/uptime"

JavaScript

const response = await fetch("https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors/mon_01J9Z3K8X4M2N6P8Q0R2S4T6V8/uptime", {
  headers: { Authorization: `Bearer ${process.env.UUP_API_TOKEN}` },
});
console.log(await response.json());

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.uup.dev/v1/projects/prj_01J9Z3K8X4M2N6P8Q0R2S4T6V8/monitors/mon_01J9Z3K8X4M2N6P8Q0R2S4T6V8/uptime",
    headers={"Authorization": f"Bearer {os.environ['UUP_API_TOKEN']}"},
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

The answer gives the uptime percentage over each window the dashboard shows, with the time we were watching and the hours not measured beside it. Uptime from the API says how to read them and how to show them.

When a call is refused

A refusal comes with a status and a body that says what to do. The examples above print the body as it comes, except Python’s, which raises an error for any status from 400. Errors and limits lists every refusal.

Next

• Creating Monitors by API: one example for each Monitor type.
• Reference: every route, with its fields.