About 10 minutes

Build your first integration

Create a least-privilege token, retrieve monitor data, perform one safe control action, and verify a test webhook.

Step 1

Create a restricted token

Open Account > Integrations and create a token dedicated to this integration. Select only the permissions and monitors it needs.

Name the token after the consuming application.
Select monitors:read and monitors:control.
Choose Selected monitors only and select a non-critical test monitor.
Choose an expiry and create the token.
Copy the token immediately. It cannot be displayed again.

Treat the token like a password. Store it in a secret manager or protected environment variable. Never place it in frontend JavaScript, mobile application code, source control, screenshots, or support requests.

Open Integrations

Step 2

List accessible monitors

Set the copied token as an environment variable, then request the monitor collection. Selected-monitor tokens only return authorized resources.

curl

curl --fail-with-body \
  --connect-timeout 5 \
  --max-time 15 \
  "https://api.uptimebasics.com/v1/monitors?limit=25" \
  -H "Authorization: Bearer $UPTIME_API_TOKEN" \
  -H "Accept: application/json"

JavaScript

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 15_000);

const response = await fetch(
  'https://api.uptimebasics.com/v1/monitors?limit=25',
  {
    headers: {
      Authorization: `Bearer ${process.env.UPTIME_API_TOKEN}`,
      Accept: 'application/json'
    },
    signal: controller.signal
  }
);
clearTimeout(timeout);
if (!response.ok) throw new Error(`API returned ${response.status}`);
const page = await response.json();

Python 3

import os
import requests

response = requests.get(
    "https://api.uptimebasics.com/v1/monitors",
    params={"limit": 25},
    headers={
        "Authorization": f"Bearer {os.environ['UPTIME_API_TOKEN']}",
        "Accept": "application/json",
    },
    timeout=(5, 15),
)
response.raise_for_status()
page = response.json()

PHP 8

<?php
$token = getenv('UPTIME_API_TOKEN');
$curl = curl_init('https://api.uptimebasics.com/v1/monitors?limit=25');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($curl);
if ($body === false || curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) {
    throw new RuntimeException('Uptime Basics API request failed.');
}
$page = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

PowerShell 7

$headers = @{
  Authorization = "Bearer $env:UPTIME_API_TOKEN"
  Accept = 'application/json'
}
$page = Invoke-RestMethod `
  -Uri 'https://api.uptimebasics.com/v1/monitors?limit=25' `
  -Headers $headers `
  -TimeoutSec 15

Keep the returned monitor id. IDs are opaque strings; do not parse or infer information from them.

Step 3

Pause a test monitor safely

Use a unique idempotency key for every intended change. If a network interruption makes the result uncertain, retry the same request with the same key.

Pause a selected test monitor

curl --fail-with-body -X POST \
  "https://api.uptimebasics.com/v1/monitors/YOUR_MONITOR_ID/pause" \
  -H "Authorization: Bearer $UPTIME_API_TOKEN" \
  -H "Idempotency-Key: pause-test-$(date +%s)" \
  -H "Content-Type: application/json"

Only pause a monitor you are authorized to control and prepared to stop checking. Activate it after the test using POST /monitors/{monitorId}/activate with a new idempotency key.

Step 4

Create and verify a test webhook

In Account > Integrations, create an HTTPS endpoint, select one test monitor and one event, save the signing secret, then use Send test. Your receiver must verify the timestamped HMAC signature over the exact raw request body.

Read the raw bytes before JSON parsing.
Reject timestamps outside your allowed tolerance.
Calculate HMAC-SHA256 over timestamp + "." + rawBody.
Compare signatures in constant time.
Deduplicate using eventId; track attempts with deliveryId.

Open verification examples

Step 5

Production readiness check

Use one token per application and the smallest practical scopes.
Use /capabilities instead of hard-coding plan assumptions.
Follow opaque cursors until nextCursor is null.
Set connection and total timeouts and retry only transient failures.
Honor 429, Retry-After, and rate-limit headers.
Rotate tokens and webhook secrets without committing them to source control.
Log X-Request-Id, but never log bearer tokens or signing secrets.

Read reliability guidance Browse all operations