UptimeSam

API

Manage a board's monitors and incidents from your own code, CI or infrastructure tools, and read its status.

Authentication

Every request carries one of your board’s API keys:

Authorization: Bearer usam_...

Create keys as a board admin under Configure → API. A key is shown once, when you create it; UptimeSam keeps only a hash. A key acts on its own board, with what an admin of the board can do, and can be revoked at any time.

Bodies are JSON (Content-Type: application/json) and so are answers. Times are UTC, in ISO 8601.

Limits and errors

Each key can make 120 requests a minute. Past that the answer is 429 with a Retry-After header.

Errors look the same everywhere:

{"error": {"code": "invalid", "message": "The monitor could not be saved.", "fields": {"url": ["can't be blank"]}}}
Status Code When
401 unauthorized No key, or one that does not exist
403 board_unavailable The board is locked or its plan has ended
403 monitor_limit_reached The plan’s monitors are all in use
404 not_found No such monitor or incident on this board
422 invalid A field is wrong; fields says which
429 rate_limited Too many requests

Monitors

Method Path
GET /api/v1/monitors Every monitor of the board
POST /api/v1/monitors Add one
GET /api/v1/monitors/:id One, with its uptime over 24 hours, 7, 30 and 90 days
PATCH /api/v1/monitors/:id Change the fields you send
DELETE /api/v1/monitors/:id Delete it and its history
POST /api/v1/monitors/:id/pause Stop checking
POST /api/v1/monitors/:id/resume Start again

Add a monitor

curl -X POST https://uptimesam.com/api/v1/monitors \
  -H "Authorization: Bearer $UPTIMESAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "API", "type": "http", "url": "https://api.example.com/health", "interval_seconds": 60}'

The answer is 201 with the monitor under data. Its first check runs within seconds.

Fields

Field For
name all Required
type all http, keyword, ssl, tcp, dns or heartbeat. Set when created, fixed after
url http, keyword, ssl The address to check
host, port tcp, dns port for tcp only
method http, keyword GET by default
headers http, keyword An object, like {"Authorization": "Bearer ..."}
body http, keyword Sent with POST, PUT, PATCH and DELETE
expected_statuses http, keyword Like 200-399 or 200,204
follow_redirects http, keyword true by default
keyword, keyword_mode keyword keyword_mode is contains or not_contains
json_path, json_expected http, keyword A field of a JSON answer, like data.status, and the value it must have
dns_record_type, dns_expected_value dns
grace_seconds heartbeat How late a ping may be
interval_seconds all Down to your plan’s shortest interval
retries, retry_interval_seconds, timeout_ms all but heartbeat
slow_threshold_ms all but heartbeat Alert after three checks in a row slower than this
reminder_minutes all While down, alert again every 15, 30, 60, 180 or 720 minutes
ssl_warn_days, check_domain http, keyword, ssl Certificate and domain expiry warnings
alert_routing, alert_channels all all, or selected with a list like ["email", "chat:<id>"]
public, public_name all Shown on the status page, and under which name
group all The group’s name; created if new, "" for none

A monitor also has status (pending, up, down, paused or maintenance), last_checked_at, last_latency_ms, last_error, ssl_expires_at, domain_expires_at and, for heartbeats, the heartbeat_url your job should call.

Incidents

Method Path
GET /api/v1/incidents Open ones first, then the most recent
POST /api/v1/incidents Post an incident
GET /api/v1/incidents/:id One, with its updates
POST /api/v1/incidents/:id/updates Post an update; resolved closes it 
curl -X POST https://uptimesam.com/api/v1/incidents \
  -H "Authorization: Bearer $UPTIMESAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Slow logins", "impact": "minor", "status": "investigating", "message": "We are looking into it."}'

impact is none, minor, major or critical; status is investigating, identified, monitoring or resolved. monitor_ids lists the monitors it affects. Like the form, posting tells the board’s alert channels and email subscribers; send "notify": false to post quietly.

Status

GET /api/v1/status answers what the board’s status page shows: the headline and each public monitor with its uptime and last 30 days. It is the same as the public /s/<board>/status.json, but works for private and password-protected pages too.