API Reference

UptimeGuard REST API — programmatic access to monitors, alerts, and uptime data. Base URL: https://api.uptimeguard.io/v1

Getting Started

Authenticate every request with your API key in the Authorization header. Generate keys from your dashboard under Settings → API Keys. All responses are JSON-encoded; request bodies must use Content-Type: application/json.

Rate limits: 120 requests per minute for standard plans, 600 per minute for Enterprise. A 429 Too Many Requests response includes a Retry-After header. Errors return a structured JSON body with error.code and error.message fields.

Example header for authenticated requests:

Authorization: Bearer ug_live_sk_7f3a9c2e1b4d8f6a0e5c9d2b7a1f4e8c

Endpoints

Core resources for managing monitors and retrieving status data.

POST

/monitors

Create a new uptime monitor. Supports HTTP(S), TCP, and ICMP checks. Required fields: name, url, type, interval_seconds. Optional: regions, tags, alert_channels[].

Response: 201 Created — returns the monitor object with id, status, created_at.

GET

/monitors

List all monitors. Query parameters: page (default 1), per_page (default 25, max 100), status (active | paused | deleted), tag (filter by tag).

Response: 200 OK — returns { monitors: [], total: number, page: number }.

GET

/monitors/:id

Retrieve a single monitor by its UUID. Includes current status, last check timestamp, and associated alert channels.

Response: 200 OK — full monitor object. Returns 404 if not found.

PUT

/monitors/:id

Update an existing monitor. Partial updates supported — send only the fields you want to change. You cannot change the monitor type after creation.

Response: 200 OK — returns the updated monitor object.

DELETE

/monitors/:id

Permanently delete a monitor and all its associated check history. This action is irreversible. Paused monitors must be deleted explicitly — they are not auto-removed.

Response: 204 No Content on success. 404 if the monitor does not exist.

GET

/monitors/:id/status

Retrieve the latest status and uptime percentage for a monitor. Returns current_state (up | down | degraded), uptime_24h, uptime_7d, uptime_30d as percentages, and last_incident_at.

Response: 200 OK — status summary object.

GET

/monitors/:id/incidents

List downtime incidents for a monitor. Query parameters: from, to (ISO 8601 timestamps), severity (critical | warning).

Response: 200 OK — returns { incidents: [], total: number }. Each incident includes started_at, resolved_at, duration_seconds, region.

POST

/monitors/:id/pause

Temporarily pause checks for a monitor. Useful during planned maintenance windows. Accepts optional resume_at (ISO 8601) for auto-resumption.

Response: 200 OK — returns the monitor with status: "paused".

Examples

Create an HTTP Monitor

Create a monitor that checks https://shop.acmecorp.io every 60 seconds from three regions:

curl -X POST https://api.uptimeguard.io/v1/monitors \
  -H "Authorization: Bearer ug_live_sk_7f3a9c2e1b4d8f6a0e5c9d2b7a1f4e8c" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Shop — Production",
    "url": "https://shop.acmecorp.io",
    "type": "https",
    "interval_seconds": 60,
    "regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
    "tags": ["production", "ecommerce"],
    "alert_channels": ["ch_slack_9x2k4m", "ch_email_ops@acmecorp.io"]
  }'

Response (201 Created):

{
  "id": "mon_8d4f2a1c6e9b3f7a",
  "name": "ACME Shop — Production",
  "url": "https://shop.acmecorp.io",
  "type": "https",
  "status": "active",
  "interval_seconds": 60,
  "regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
  "tags": ["production", "ecommerce"],
  "alert_channels": [
    { "id": "ch_slack_9x2k4m", "type": "slack" },
    { "id": "ch_email_ops@acmecorp.io", "type": "email" }
  ],
  "created_at": "2025-01-14T09:32:17Z",
  "updated_at": "2025-01-14T09:32:17Z"
}

List Monitors with Filtering

curl "https://api.uptimeguard.io/v1/monitors?status=active&tag=production&per_page=10" \
  -H "Authorization: Bearer ug_live_sk_7f3a9c2e1b4d8f6a0e5c9d2b7a1f4e8c"

Response (200 OK):

{
  "monitors": [
    {
      "id": "mon_8d4f2a1c6e9b3f7a",
      "name": "ACME Shop — Production",
      "url": "https://shop.acmecorp.io",
      "type": "https",
      "status": "active",
      "current_state": "up",
      "uptime_24h": 99.97,
      "tags": ["production", "ecommerce"]
    },
    {
      "id": "mon_3b7e9c5a1d2f8e4g",
      "name": "ACME API Gateway",
      "url": "https://api.acmecorp.io/health",
      "type": "https",
      "status": "active",
      "current_state": "up",
      "uptime_24h": 100.0,
      "tags": ["production", "backend"]
    }
  ],
  "total": 2,
  "page": 1
}

Delete a Monitor

curl -X DELETE https://api.uptimeguard.io/v1/monitors/mon_8d4f2a1c6e9b3f7a \
  -H "Authorization: Bearer ug_live_sk_7f3a9c2e1b4d8f6a0e5c9d2b7a1f4e8c"

Response: 204 No Content — empty body on success.

Error Response Format

When a request fails, UptimeGuard returns a consistent error envelope:

{
  "error": {
    "code": "MONITOR_NOT_FOUND",
    "message": "No monitor exists with ID 'mon_invalid_id'. Verify the monitor ID or create a new monitor first.",
    "request_id": "req_4a8f2c1d9e3b7f6a"
  }
}

Common error codes: INVALID_API_KEY, RATE_LIMIT_EXCEEDED, MONITOR_NOT_FOUND, VALIDATION_ERROR, MONITOR_ALREADY_EXISTS (when creating a duplicate URL).