Monitors API

Create, update, pause, and delete monitors programmatically.

Monitors define what endpoints or services to check for uptime. Each monitor has a specific type (HTTPS, TCP, Ping) determined by the settings object structure, and can be deployed across multiple global regions for comprehensive monitoring coverage.

Note: The monitor type is automatically determined from your settings object (e.g., “https” settings create HTTPS monitors, “tcp” settings create TCP monitors).

Dashboard vs API Defaults: The web dashboard uses different defaults for better user experience (e.g., fail_threshold=2, timeout=10). The API uses the values documented here.

Monitor Types

HTTPS/HTTP

Website monitoring

TCP

Port connectivity

Ping

ICMP monitoring

All monitor types can be deployed across 16 global regions for comprehensive coverage and reliability testing from multiple geographic locations.

GET/api/monitors

Retrieve a paginated list of monitors with optional filtering and sorting.

Query Parameters

Name	Type	Required	Description
page	`integer`	No	Page number for paginationDefault: `1`Example: `2`
per_page	`integer`	No	Items per page (max 100)Default: `50`Example: `25`
sort	`string`	No	Sort field: name, created_at, updated_atDefault: `created_at`Example: `name`
order	`string`	No	Sort order: asc, descDefault: `desc`Example: `asc`
active	`boolean`	No	Filter by monitor statusExample: `true`
monitor_type	`string`	No	Filter by monitor type: https, tcp, pingExample: `https`

Example Request

curl -X GET "https://api.uptime-monitor.io/api/monitors?page=1&per_page=20&sort=name&order=asc" \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "monitors": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "🌐 My Website",
        "active": true,
        "check_interval": 300,
        "timeout": 30,
        "fail_threshold": 3,
        "regions": ["us-east-1", "eu-west-1"],
        "settings": {
          "https": {
            "url": "https://example.com",
            "check_certificate_expiration": true
          }
        },
        "contacts": ["507f1f77bcf86cd799439012"],
        "last_status": "up",
        "last_status_change": 1640995800,
        "created_at": 1640995200
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 45,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  }
}

GET/api/monitors/:id

Retrieve detailed information about a specific monitor.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Monitor IDExample: `507f1f77bcf86cd799439011`

Example Request

curl -X GET https://api.uptime-monitor.io/api/monitors/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "🌐 My Website",
    "active": true,
    "check_interval": 300,
    "timeout": 30,
    "fail_threshold": 3,
    "regions": ["us-east-1", "eu-west-1"],
    "settings": {
      "https": {
        "url": "https://example.com",
        "check_certificate_expiration": true
      }
    },
    "contacts": ["507f1f77bcf86cd799439012"],
    "last_status": "up",
    "last_status_change": 1640995800,
    "created_at": 1640995200
  }
}

Error Responses

404MONITOR_NOT_FOUND

Monitor with the specified ID does not exist

POST/api/monitors

Create a new monitor to track website or service uptime.

Body Parameters

Name	Type	Required	Description
name	`string`	Yes	Monitor display name (max 100 characters)Example: `🌐 My Website`
active	`boolean`	No	Monitor statusDefault: `true`
check_interval	`integer`	No	Check interval in seconds (10-600)Default: `300`Example: `120`
timeout	`integer`	No	Check timeout in seconds (5-60)Default: `30`Example: `15`
fail_threshold	`integer`	No	Failed checks before marking as down (1-10)Default: `2`Example: `3`
regions	`array`	No	Monitoring regions. Must specify at least one region from the available regions listed belowDefault: `[]`Example: `["us-east-1", "eu-west-1"]`
settings	`object`	Yes	Monitor type-specific configuration
contacts	`array`	No	Array of contact IDs for notificationsExample: `["507f1f77bcf86cd799439012"]`

Example Request

curl -X POST https://api.uptime-monitor.io/api/monitors \
  -H "Authorization: Bearer um_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "🌐 My Website",
    "check_interval": 300,
    "timeout": 30,
    "fail_threshold": 2,
    "regions": ["us-east-1", "eu-west-1"],
    "settings": {
      "https": {
        "url": "https://example.com",
        "check_certificate_expiration": true
      }
    },
    "contacts": ["507f1f77bcf86cd799439012"]
  }'

Example Response

{
  "status": "ok",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "🌐 My Website",
    "active": true,
    "check_interval": 300,
    "timeout": 30,
    "fail_threshold": 2,
    "regions": ["us-east-1", "eu-west-1"],
    "settings": {
      "https": {
        "url": "https://example.com",
        "check_certificate_expiration": true
      }
    },
    "contacts": ["507f1f77bcf86cd799439012"],
    "last_status": "up",
    "last_status_change": 1640995800,
    "created_at": 1640995200
  }
}

Error Responses

422VALIDATION_ERROR

Required fields are missing or invalid

Monitor Configuration Examples

Each monitor type requires specific configuration in the settings object. Here are examples for each supported monitor type:

HTTPS/HTTP Monitor

Monitor website availability and optionally check SSL certificate expiration.

HTTPS Monitor Configuration

{
  "name": "🌐 My Website",
  "check_interval": 300,
  "timeout": 30,
  "fail_threshold": 2,
  "regions": ["us-east-1", "eu-west-1"],
  "settings": {
    "https": {
      "url": "https://example.com",
      "check_certificate_expiration": true
    }
  },
  "contacts": ["507f1f77bcf86cd799439012"]
}

TCP Monitor

Monitor TCP port connectivity for databases, APIs, and other services.

TCP Monitor Configuration

{
  "name": "🔌 Database Server",
  "check_interval": 120,
  "timeout": 15,
  "fail_threshold": 3,
  "regions": ["us-east-1"],
  "settings": {
    "tcp": {
      "url": "tcp://db.example.com:5432"
    }
  },
  "contacts": ["507f1f77bcf86cd799439012"]
}

Ping Monitor

Monitor server connectivity using ICMP ping packets.

Ping Monitor Configuration

{
  "name": "🏓 Server Connectivity",
  "check_interval": 60,
  "timeout": 10,
  "fail_threshold": 5,
  "regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
  "settings": {
    "ping": {
      "url": "ping://8.8.8.8"
    }
  },
  "contacts": ["507f1f77bcf86cd799439012"]
}

PUT/api/monitors/:id

Update an existing monitor's configuration. Only provide fields you want to change.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Monitor IDExample: `507f1f77bcf86cd799439011`

Body Parameters

Name	Type	Required	Description
name	`string`	No	Updated monitor display nameExample: `🌐 Updated Website Name`
active	`boolean`	No	Monitor status
check_interval	`integer`	No	Check interval in seconds (10-600)Example: `120`
timeout	`integer`	No	Check timeout in seconds (5-60)
fail_threshold	`integer`	No	Failed checks before marking as down (1-10)
regions	`array`	No	Monitoring regions. See available regions below
settings	`object`	No	Monitor type-specific configuration
contacts	`array`	No	Array of contact IDs for notifications

Example Request

curl -X PUT https://api.uptime-monitor.io/api/monitors/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "🌐 Updated Website Name",
    "check_interval": 120,
    "contacts": ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"]
  }'

Example Response

{
  "status": "ok",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "🌐 Updated Website Name",
    "active": true,
    "check_interval": 120,
    "timeout": 30,
    "fail_threshold": 2,
    "regions": ["us-east-1", "eu-west-1"],
    "settings": {
      "https": {
        "url": "https://example.com",
        "check_certificate_expiration": true
      }
    },
    "contacts": ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"],
    "last_status": "up",
    "last_status_change": 1640995800,
    "created_at": 1640995200
  }
}

Error Responses

404MONITOR_NOT_FOUND

Monitor with the specified ID does not exist

422VALIDATION_ERROR

Invalid field values provided

DELETE/api/monitors/:id

Permanently delete a monitor and all its historical data. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Monitor IDExample: `507f1f77bcf86cd799439011`

Example Request

curl -X DELETE https://api.uptime-monitor.io/api/monitors/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_xxxx"

Example Response

HTTP 204 No Content

Error Responses

404MONITOR_NOT_FOUND

Monitor with the specified ID does not exist

Deletion Warning

Deleting a monitor permanently removes all historical data, statistics, and incident records. This action cannot be undone. Consider pausing the monitor instead if you only need to temporarily stop notifications while continuing to collect monitoring data.

POST/api/monitors/:id/pause

Pause alerting for a monitor. Monitoring continues but no notifications will be sent.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Monitor IDExample: `507f1f77bcf86cd799439011`

Example Request

curl -X POST https://api.uptime-monitor.io/api/monitors/507f1f77bcf86cd799439011/pause \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "🌐 My Website",
    "active": false,
    "updated_at": 1640995800
  }
}

Error Responses

404MONITOR_NOT_FOUND

Monitor with the specified ID does not exist

POST/api/monitors/:id/resume

Resume alerting for a paused monitor. Notifications will be sent again.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Monitor IDExample: `507f1f77bcf86cd799439011`

Example Request

curl -X POST https://api.uptime-monitor.io/api/monitors/507f1f77bcf86cd799439011/resume \
  -H "Authorization: Bearer um_xxxx"

Example Response

{
  "status": "ok",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "🌐 My Website",
    "active": true,
    "updated_at": 1640995800
  }
}

Error Responses

404MONITOR_NOT_FOUND

Monitor with the specified ID does not exist

Available Regions

Monitors can be deployed across the following AWS regions where our checker infrastructure is deployed. Using multiple regions provides better coverage, redundancy, and helps identify region-specific connectivity issues.

Tip: You can get the current list of supported regions and their checker IP addresses at https://uptime-monitor.io/web_api/checker_ip_addresses. This is useful for whitelisting our monitoring infrastructure in your firewall rules.

North America

us-east-1 (N. Virginia)
us-east-2 (Ohio)
us-west-1 (N. California)
us-west-2 (Oregon)

Europe

eu-west-1 (Ireland)
eu-central-1 (Frankfurt)
eu-central-2 (Zurich)
eu-north-1 (Stockholm)

Asia Pacific

ap-east-1 (Hong Kong)
ap-northeast-1 (Tokyo)
ap-northeast-2 (Seoul)
ap-southeast-1 (Singapore)
ap-southeast-2 (Sydney)

Other Regions

sa-east-1 (São Paulo)
af-south-1 (Cape Town)
me-central-1 (UAE)

← Contacts API Incidents API →