Monitors API
Create, update, and manage uptime monitors programmatically.
Permissions required: monitors.read, monitors.create, monitors.update, or monitors.delete
The Monitor Object
Attributes:
| Attribute | Type | Description |
|---|---|---|
id | string | Unique identifier with mon_ prefix |
object | string | Always "monitor" |
name | string | Display name for the monitor |
url | string | URL or host to monitor |
type | string | Monitor type: http, tcp, dns, ping |
status | string | Current status: up, down, pending, paused |
interval_seconds | integer | Check interval in seconds |
timeout_seconds | integer | Request timeout in seconds |
method | string | HTTP method (for HTTP monitors) |
expected_status_code | integer | Expected HTTP status code |
created | integer | Unix timestamp of creation |
updated | integer | Unix timestamp of last update |
metadata | object | Custom key-value pairs |
List Monitors
Returns a list of monitors.
GET /monitorsPermission: monitors.read
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of objects (1-100, default 10) |
starting_after | string | Cursor for pagination |
ending_before | string | Cursor for reverse pagination |
status | string | Filter by status: up, down, pending, paused |
type | string | Filter by type: http, tcp, dns, ping |
search | string | Search by name |
sort | string | Sort field (prefix with - for descending) |
Request:
Response:
Create Monitor
Creates a new monitor.
POST /monitorsPermission: monitors.create
Body Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
name | Yes | string | Display name |
url | Yes | string | URL or host to monitor |
type | Yes | string | Monitor type: http, tcp, dns, ping |
interval_seconds | No | integer | Check interval (default: 60) |
timeout_seconds | No | integer | Request timeout (default: 30) |
method | No | string | HTTP method (default: GET) |
expected_status_code | No | integer | Expected status (default: 200) |
metadata | No | object | Custom key-value pairs |
Request:
Response (201 Created):
Get Monitor
Retrieves a monitor by ID.
GET /monitors/:idPermission: monitors.read
Request:
Response:
Update Monitor
Updates a monitor. Only include fields you want to change.
PATCH /monitors/:idPermission: monitors.update
Body Parameters:
All parameters are optional. Include only fields to update.
| Parameter | Type | Description |
|---|---|---|
name | string | Display name |
url | string | URL or host |
interval_seconds | integer | Check interval |
timeout_seconds | integer | Request timeout |
method | string | HTTP method |
expected_status_code | integer | Expected status |
metadata | object | Custom key-value pairs (merged) |
Request:
Response:
Delete Monitor
Permanently deletes a monitor.
DELETE /monitors/:idPermission: monitors.delete
Request:
Response: 204 No Content
Pause Monitor
Pauses monitoring. The monitor status changes to paused and checks stop.
POST /monitors/:id/pausePermission: monitors.update
Request:
Response:
Resume Monitor
Resumes a paused monitor.
POST /monitors/:id/resumePermission: monitors.update
Request:
Response:
List Checks
Returns recent check results for a monitor.
GET /monitors/:id/checksPermission: monitors.read
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of checks (1-100, default 10) |
starting_after | string | Cursor for pagination |
Request:
Response: