Documentation

REST API v1

Manage monitors, read uptime and incidents and integrate UptimeAnchor with your tools. All requests and responses use JSON.

Base URL

https://uptimeanchor.com/api/v1

OpenAPI specification/api/v1/openapi.json

Authentication

Every request must include an API key in the Authorization header using the Bearer scheme. Keys belong to an organisation and don't expire until you revoke them.

Authorization: Bearer vg_live_xxxxxxxxxxxxxxxxxxxxxxxx

You can create and revoke keys in Settings → API

READ
Read-only access to all of the organisation's resources.
WRITE
Read and write: create, update, pause and delete monitors.
MONITOR
Read-only access limited to a single monitor, ideal for external dashboards.

Errors

On error the response has a 4xx or 5xx HTTP status and a JSON body with an error object containing code (stable, use it in your code), message (human-readable) and optionally details.

{
  "error": {
    "code": "invalid_parameter",
    "message": "'limit' must be between 1 and 100."
  }
}

HTTP	code	Description
400	invalid_parameter	Invalid query parameter.
400	invalid_json	The request body is not a valid JSON object.
422	validation_error	Invalid data; details lists the fields with errors.
401	unauthorized	Missing or invalid API key.
403	insufficient_scope	The key lacks the required scope (e.g. WRITE is needed).
403	plan_limit	The operation exceeds your plan limits.
404	not_found	Resource doesn't exist or isn't accessible.
429	rate_limited	Rate limit exceeded; wait Retry-After seconds.
500	internal_error	Internal error; please retry later.

Limits apply per API key over 60-second windows: 60 requests per minute on the Free plan and 300 on paid plans. Every response includes the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; beyond the limit you get a 429 with a Retry-After header.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 30

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (60 requests per minute)." } }

Pagination

List endpoints use cursor pagination. Pass limit (1–100, default 50) and, for subsequent pages, the pagination.nextCursor value from the previous response as cursor. When nextCursor is null you've reached the end.

curl "https://uptimeanchor.com/api/v1/monitors?limit=100&cursor=cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Monitors

List monitors

GET/api/v1/monitors

Returns the organisation's monitors, ordered by ID. Credentials stored in the configuration are always redacted.

Parameters

Name	In	Type	Description
limit	query	integer	Items per page, 1 to 100 (default 50).
cursor	query	string	Value of pagination.nextCursor from the previous page.
status	query	enum	Filter by status: UP, DOWN, PAUSED, MAINTENANCE, PENDING (comma-separated values allowed).
type	query	enum	Filter by type, e.g. HTTP,PORT.
search	query	string	Search in name and target.

Request

curl "https://uptimeanchor.com/api/v1/monitors?status=DOWN&limit=50" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": [
    {
      "id": "cm2x8f1k30001qz0v",
      "name": "Checkout",
      "type": "HTTP",
      "status": "UP",
      "target": "https://shop.example.com/checkout",
      "port": null,
      "interval": 60,
      "timeout": 30,
      "regions": ["eu-south", "eu-central"],
      "config": { "method": "GET", "expectedStatus": "200-299" },
      "sslCheck": true,
      "sslExpiryReminders": true,
      "heartbeatUrl": null,
      "tags": ["produzione"],
      "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
      "lastCheckedAt": "2026-10-18T09:41:00.000Z",
      "lastResponseMs": 182,
      "lastError": null,
      "sslExpiresAt": "2027-01-12T23:59:59.000Z",
      "sslIssuer": "R11",
      "pausedAt": null,
      "createdAt": "2026-03-02T10:15:22.000Z",
      "updatedAt": "2026-10-18T09:41:00.000Z"
    }
  ],
  "pagination": { "limit": 50, "nextCursor": null }
}

Create a monitor

POST/api/v1/monitors

Creates a new monitor and schedules the first check immediately. Requires a WRITE key. Responds 201 with the created monitor; for HEARTBEAT monitors the response includes heartbeatUrl.

Parameters

Name	In	Type	Description
name*	body	string	Monitor name (max 120 characters).
type*	body	enum	HTTP, KEYWORD, PING, PORT, UDP, HEARTBEAT, DNS or DOMAIN.
target	body	string	URL (HTTP/KEYWORD) or host or domain. Not required for HEARTBEAT.
port	body	integer	Port, required for PORT and UDP.
interval	body	integer	Interval in seconds, 30 to 86400 (default 300). The minimum depends on your plan.
timeout	body	integer	Timeout in seconds, 1 to 60 (default 30).
regions	body	string[]	Check POP ids (e.g. eu-south). GET /api/v1/regions returns the up-to-date list.
config	body	object	Type-specific options: method, headers, body, expectedStatus, keyword, keywordMode, dnsRecordType, dnsExpected, udpPayload… (see the OpenAPI spec).
gracePeriod	body	integer	HEARTBEAT only: grace period in seconds (default 60).
sslExpiryReminders	body	boolean	Certificate expiry reminders (default true).
alertContacts	body	object[]	Contacts to notify: alertContactId, threshold (minutes to wait before alerting) and recurrence (repeat in minutes, 0 = never).
tags	body	string[]	Up to 20 tags.

Request

curl -X POST "https://uptimeanchor.com/api/v1/monitors" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout",
    "type": "HTTP",
    "target": "https://shop.example.com/checkout",
    "interval": 60,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 0, "recurrence": 0 }],
    "tags": ["produzione"]
  }'

Response

{
  "data": {
    "id": "cm2x8f1k30001qz0v",
    "name": "Checkout",
    "type": "HTTP",
    "status": "UP",
    "target": "https://shop.example.com/checkout",
    "port": null,
    "interval": 60,
    "timeout": 30,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "sslCheck": true,
    "sslExpiryReminders": true,
    "heartbeatUrl": null,
    "tags": ["produzione"],
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
    "lastCheckedAt": "2026-10-18T09:41:00.000Z",
    "lastResponseMs": 182,
    "lastError": null,
    "sslExpiresAt": "2027-01-12T23:59:59.000Z",
    "sslIssuer": "R11",
    "pausedAt": null,
    "createdAt": "2026-03-02T10:15:22.000Z",
    "updatedAt": "2026-10-18T09:41:00.000Z"
  }
}

Retrieve a monitor

GET/api/v1/monitors/{id}

Returns a single monitor with its current status, last check, SSL data and attached contacts.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.

Request

curl "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": {
    "id": "cm2x8f1k30001qz0v",
    "name": "Checkout",
    "type": "HTTP",
    "status": "UP",
    "target": "https://shop.example.com/checkout",
    "port": null,
    "interval": 60,
    "timeout": 30,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "sslCheck": true,
    "sslExpiryReminders": true,
    "heartbeatUrl": null,
    "tags": ["produzione"],
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
    "lastCheckedAt": "2026-10-18T09:41:00.000Z",
    "lastResponseMs": 182,
    "lastError": null,
    "sslExpiresAt": "2027-01-12T23:59:59.000Z",
    "sslIssuer": "R11",
    "pausedAt": null,
    "createdAt": "2026-03-02T10:15:22.000Z",
    "updatedAt": "2026-10-18T09:41:00.000Z"
  }
}

Update a monitor

PATCH/api/v1/monitors/{id}

Updates only the fields you send; the others stay unchanged. Accepts the same fields as creation. Requires a WRITE key.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.

Request

curl -X PATCH "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval": 120, "name": "Checkout (EU)" }'

Response

{
  "data": { "id": "cm2x8f1k30001qz0v", "name": "Checkout (EU)", "interval": 120, "…": "…" }
}

Delete a monitor

DELETE/api/v1/monitors/{id}

Permanently deletes the monitor along with its checks and incidents. Requires a WRITE key.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.

Request

curl -X DELETE "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{ "data": { "id": "cm2x8f1k30001qz0v", "deleted": true } }

Pause a monitor

POST/api/v1/monitors/{id}/pause

Suspends the monitor's checks and alerts, for example during a release. Requires a WRITE key.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.

Request

curl -X POST "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/pause" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{ "data": { "id": "cm2x8f1k30001qz0v", "status": "PAUSED", "pausedAt": "2026-10-18T10:00:00.000Z", "…": "…" } }

Resume a monitor

POST/api/v1/monitors/{id}/resume

Reactivates a paused monitor and schedules a check right away. Requires a WRITE key.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.

Request

curl -X POST "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/resume" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{ "data": { "id": "cm2x8f1k30001qz0v", "status": "PENDING", "pausedAt": null, "…": "…" } }

Monitor uptime

GET/api/v1/monitors/{id}/uptime

Uptime percentage over the requested period, 1-, 7- and 30-day ratios, downtime and a daily breakdown.

Parameters

Name	In	Type	Description
id*	path	string	Monitor ID.
days	query	integer	Number of days, 1 to 90 (default 30).

Request

curl "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/uptime?days=30" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": {
    "monitorId": "cm2x8f1k30001qz0v",
    "days": 30,
    "uptime": 99.982,
    "ratios": { "1d": 99.46, "7d": 99.92, "30d": 99.982 },
    "downtimeSeconds": 466,
    "daily": [
      { "date": "2026-10-17", "total": 1440, "up": 1440, "uptime": 100, "avgResponseMs": 179, "downtimeSeconds": 0 },
      { "date": "2026-10-18", "total": 1440, "up": 1432, "uptime": 99.46, "avgResponseMs": 201, "downtimeSeconds": 466 }
    ]
  }
}

Incidents

List incidents

GET/api/v1/incidents

Returns incidents, most recent first, with cause, duration and status.

Parameters

Name	In	Type	Description
limit	query	integer	Items per page, 1 to 100 (default 50).
cursor	query	string	Value of pagination.nextCursor from the previous page.
status	query	enum	OPEN or RESOLVED.
monitorId	query	string	Only incidents for one monitor.

Request

curl "https://uptimeanchor.com/api/v1/incidents?status=OPEN" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": [
    {
      "id": "cm2y0c7d20009qz0v",
      "monitorId": "cm2x8f1k30001qz0v",
      "monitorName": "Checkout",
      "status": "OPEN",
      "cause": "HTTP 503 Service Unavailable",
      "details": null,
      "rootCause": null,
      "startedAt": "2026-10-18T09:42:11.000Z",
      "resolvedAt": null,
      "acknowledgedAt": null,
      "durationSeconds": 312
    }
  ],
  "pagination": { "limit": 50, "nextCursor": null }
}

Status pages

List status pages

GET/api/v1/status-pages

Returns the organisation's status pages with public URL, custom domain and included monitors.

Request

curl "https://uptimeanchor.com/api/v1/status-pages" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": [
    {
      "id": "cm2x7e4q00002qz0v",
      "name": "Status",
      "slug": "example",
      "url": "https://status.example.com",
      "customDomain": "status.example.com",
      "published": true,
      "passwordProtected": false,
      "language": "it",
      "theme": "AUTO",
      "accentColor": "#14b8a6",
      "monitors": [ "…" ]
    }
  ]
}

Alert contacts

List alert contacts

GET/api/v1/alert-contacts

Returns alert contacts. For security reasons the configuration isn't exposed: only the destination for email, SMS and calls.

Request

curl "https://uptimeanchor.com/api/v1/alert-contacts" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Response

{
  "data": [
    { "id": "cm2x9a0b10004qz0v", "type": "SLACK", "name": "On-call Slack", "enabled": true, "destination": null, "monitors": 12, "createdAt": "2026-03-02T10:20:00.000Z" },
    { "id": "cm2x9a0b10005qz0v", "type": "EMAIL", "name": "Ops", "enabled": true, "destination": "ops@example.com", "monitors": 30, "createdAt": "2026-03-02T10:21:00.000Z" }
  ]
}

Heartbeat URL

Every HEARTBEAT monitor has a secret URL. Call it at the end of each job run: if the ping doesn't arrive within interval plus grace period, the monitor goes DOWN. No API key is needed.

GETPOST/api/heartbeat/{token}

Accepts GET, POST and HEAD and replies 200 OK in plain text (404 if the token doesn't exist). Up to 60 pings per minute per token.

# crontab: esegue il backup e, solo se ha successo, invia il ping
0 3 * * *  /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://uptimeanchor.com/api/heartbeat/hb_7Qm2xK9pLr4s

# oppure da codice (Node.js)
await fetch("https://uptimeanchor.com/api/heartbeat/hb_7Qm2xK9pLr4s", { method: "POST" });

Status badges

SVG images showing a monitor's status or uptime, to embed in READMEs, wikis and websites. They're public for monitors on a published, unprotected status page; for other monitors add the key parameter with an API key.

GET/api/badge/{monitorId}

Name	In	Type	Description
type	query	enum	status (default) or uptime.
days	query	integer	Uptime period, 1 to 90 (default 30).
label	query	string	Custom left-hand text (max 40 characters).
lang	query	enum	it or en (default en).
key	query	string	API key, required for non-public monitors.

<!-- Markdown / README -->
![uptime](https://uptimeanchor.com/api/badge/cm2x8f1k30001qz0v?type=uptime&days=30)
![status](https://uptimeanchor.com/api/badge/cm2x8f1k30001qz0v?type=status&lang=it)

OpenAPI specification

The full OpenAPI 3 specification is available as JSON: import it into Postman or Insomnia, or use it to generate a client in your language.

https://uptimeanchor.com/api/v1/openapi.json