Docs

REST API

Learn how to create an API key, authenticate, and make your first requests.

This page explains how to authenticate against the UptimeX API and make your first requests. Every endpoint, with its parameters and response schema, is in the API reference.

#Base URL

All requests go over HTTPS to:

Code
https://api.uptimex.co

Requests and responses are JSON. Send Content-Type: application/json with a body.

#Authentication

The API authenticates with API keys. A key starts with upk_, is scoped to exactly one project, and acts with the role of the person who created it in that project. A key can read and write that project's monitors, channels, maintenance windows, incidents, and status page. It cannot reach account settings, billing, other projects, team members, or keys.

#Create a key

  1. Open the project's Project Settings and find Access tokens.
  2. Enter a name and choose when the key expires: 1 hour, 1 day, 7 days, 30 days, 90 days, or Never.
  3. Choose Create. The key is shown once. Copy it now.

Viewers cannot create keys. A key stops working when its creator leaves the project, and you can revoke any of your keys from the same list.

#Use the key

Send it as a Bearer token on every request:

Code
Authorization: Bearer upk_your_key

Keys cannot create keys

Keys are created and revoked in the dashboard only, so a leaked key can never mint more keys or change who has access.

#Rate limits

Requests made with API keys are limited per account, across all of the account's projects and keys: 30 requests a minute on the free plan, 120 on Pro, and 300 on Team. Over the limit, the API answers 429 with Retry-After: 60 and {"error":"rate_limited","limit":30}. See Errors.

#Create a monitor

Only url is required. This creates an HTTP monitor checked every 5 minutes:

Shell
curl -X POST https://api.uptimex.co/v1/monitors \
  -H "Authorization: Bearer upk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "name": "Marketing site", "interval_sec": 300 }'

The response is the created monitor with HTTP status 201. Its status is null until the first check completes a moment later. Omitted fields take the defaults listed in Create a monitor, and interval_sec is raised to your plan's minimum if it is lower.

Set type to keyword, api, heartbeat, scheduler, port, or dns for the other kinds. Each takes the fields its dashboard form takes: host and port for a port monitor, host, dns_record_type, and dns_expected_value for DNS, interval_sec and grace_sec for a heartbeat.

#Test before saving

POST /v1/monitors/test takes the same body as an HTTP, Keyword, or API create and runs one check without saving anything:

Shell
curl -X POST https://api.uptimex.co/v1/monitors/test \
  -H "Authorization: Bearer upk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "method": "GET" }'

The response holds status, latency_ms, connect_ms, ttfb_ms, detail, http_status, and the first 4,096 characters of the body.

#Everyday calls

CallPurpose
GET /v1/monitorsEvery monitor in the key's project, with its status and last 30 checks.
PATCH /v1/monitors/{id}Change any field. Send {"enabled": false} to pause and true to resume.
DELETE /v1/monitors/{id}Delete the monitor and its history.
GET /v1/monitors/{id}/events?limit=50The activity log, newest first, up to 200.
GET /v1/monitors/{id}/history?range=24Chart data for the last N hours, up to your plan's retention.
GET /v1/projects/{ref}/channelsThe project's notification channels.
GET /v1/projects/{ref}/maintenanceThe project's maintenance windows.
GET /v1/incidents?project={ref}The project's incidents, ongoing first. Pro and Team.

Lists are not paginated. Where a limit applies, its maximum is 200.

#Request headers on monitors

When you send request_headers on a PATCH, the list replaces the stored one. Leave the field out to keep the stored headers, send [] to remove them all, or send an entry with a name and no value to keep that header's stored value.

#The OpenAPI document

The document is served from the API itself, so you can point any client generator at it:

Code
https://api.uptimex.co/openapi.json

A rendered version lives at https://api.uptimex.co/docs, and the API reference in these docs is built from the same document.

#What's next?