The Monitorion REST API gives you programmatic control over your monitors, incidents, and alerting configuration. Integrate monitoring into your CI/CD pipelines, infrastructure-as-code workflows, or custom dashboards.
Pro+ only: API access requires a Pro, Business, or Agency plan. Generate your API key in Settings → API Keys.
All endpoints are relative to this base URL. All requests and responses use JSON. SSL is required — HTTP requests are not accepted.
Pass your API key as a Bearer token in the Authorization header on every request.
curl https://app.monitorion.com/api/v1/monitors \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
mon_ and are 48 characters long.The API enforces a rate limit of 100 requests per minute per API key. Rate limit headers are included on every response:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1718640060
When the limit is exceeded the API returns 429 Too Many Requests. Retry after the number of seconds indicated in the Retry-After header. Heartbeat ping endpoints are exempt from rate limiting.
The monitor_type field accepts one of the following values:
The interval_seconds field controls how often a monitor runs. Valid range: 30 – 86400 seconds. Plan limits apply:
| Plan | Minimum interval_seconds |
|---|---|
| Free | 300 (5 minutes) |
| Pro | 60 (1 minute) |
| Business / Agency | 30 (30 seconds) |
/monitorsReturns a paginated list of all monitors for the authenticated account.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number, default 1 |
| limit | integer | Results per page, default 20, max 100 |
{
"data": [
{
"id": "mon_01j8abc123",
"name": "Production API",
"monitor_type": "http",
"enabled": true,
"last_status": "up",
"interval_seconds": 60,
"created_at": "2026-01-15T10:30:00Z",
"config": {
"url": "https://api.example.com/health",
"method": "GET",
"expectedStatusCode": 200,
"timeout": 10
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 47,
"total_pages": 3
}
}/monitorsCreates a new monitor. Returns the created monitor object.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Human-readable monitor name |
| monitor_type | string | Yes | One of the supported monitor type values |
| config | object | Yes | Type-specific configuration (see below) |
| interval_seconds | integer | No | Check frequency. Default 300. Min 60 (Pro), 30 (Business+) |
| regions | string[] | No | Probe regions e.g. ["us-east", "eu-west"] |
| project_id | string | No | Assign to a project. Omit for personal monitors |
| Field | Type | Description |
|---|---|---|
| url | string | Full URL to monitor, including protocol |
| method | string | HTTP method: GET, POST, HEAD, PUT, DELETE. Default GET |
| expectedStatusCode | integer | Expected HTTP status code. Default 200 |
| keyword | string | Optional. Alert if this text is absent from the response body |
| timeout | integer | Request timeout in seconds. Default 10, max 30 |
| headers | object | Optional custom request headers as key/value pairs |
| followRedirects | boolean | Whether to follow HTTP redirects. Default true |
curl -X POST https://app.monitorion.com/api/v1/monitors \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Homepage",
"monitor_type": "http",
"interval_seconds": 60,
"config": {
"url": "https://example.com",
"method": "GET",
"expectedStatusCode": 200,
"keyword": "Welcome to Acme",
"timeout": 10
}
}'const res = await fetch('https://app.monitorion.com/api/v1/monitors', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Production Homepage',
monitor_type: 'http',
interval_seconds: 60,
config: {
url: 'https://example.com',
method: 'GET',
expectedStatusCode: 200,
keyword: 'Welcome to Acme',
timeout: 10,
},
}),
});
const monitor = await res.json();
console.log(monitor.data.id); // mon_01j8abc456/monitors/:idReturns the full detail of a single monitor, including its current status, last check result, and configuration.
{
"data": {
"id": "mon_01j8abc123",
"name": "Production API",
"monitor_type": "http",
"enabled": true,
"last_status": "up",
"last_checked_at": "2026-06-25T09:14:00Z",
"uptime_percentage": 99.87,
"interval_seconds": 60,
"config": {
"url": "https://api.example.com/health",
"method": "GET",
"expectedStatusCode": 200,
"timeout": 10
},
"last_check": {
"status": "up",
"response_time_ms": 143,
"status_code": 200,
"checked_at": "2026-06-25T09:14:00Z"
}
}
}/monitors/:idUpdates one or more fields on an existing monitor. Only the fields you provide are changed — all others remain as-is. Returns the updated monitor object.
curl -X PATCH https://app.monitorion.com/api/v1/monitors/mon_01j8abc123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'curl -X PATCH https://app.monitorion.com/api/v1/monitors/mon_01j8abc123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "interval_seconds": 30 }'/monitors/:idPermanently deletes a monitor and all its historical check data. This action cannot be undone. Returns 204 No Content on success.
curl -X DELETE https://app.monitorion.com/api/v1/monitors/mon_01j8abc123 \ -H "Authorization: Bearer YOUR_API_KEY"
/incidentsReturns a paginated list of incidents. Supports filtering by status.
| Param | Type | Description |
|---|---|---|
| status | string | Filter by status: open, resolved, or acknowledged |
| page | integer | Page number, default 1 |
| limit | integer | Results per page, default 20, max 100 |
{
"data": [
{
"id": "inc_01j9xyz789",
"monitor_id": "mon_01j8abc123",
"monitor_name": "Production API",
"status": "resolved",
"started_at": "2026-06-24T03:12:00Z",
"resolved_at": "2026-06-24T03:47:00Z",
"duration_seconds": 2100,
"cause": "Connection timeout after 10s"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3,
"total_pages": 1
}
}/incidents/:idReturns the full detail of a single incident including its event timeline.
{
"data": {
"id": "inc_01j9xyz789",
"monitor_id": "mon_01j8abc123",
"monitor_name": "Production API",
"status": "resolved",
"started_at": "2026-06-24T03:12:00Z",
"resolved_at": "2026-06-24T03:47:00Z",
"duration_seconds": 2100,
"cause": "Connection timeout after 10s",
"root_cause_note": "AWS us-east-1 network blip",
"timeline": [
{
"event": "down_detected",
"timestamp": "2026-06-24T03:12:00Z",
"detail": "HTTP timeout after 10s from us-east probe"
},
{
"event": "alert_sent",
"timestamp": "2026-06-24T03:12:18Z",
"detail": "Email sent to [email protected]"
},
{
"event": "acknowledged",
"timestamp": "2026-06-24T03:20:05Z",
"detail": "Acknowledged by [email protected]"
},
{
"event": "resolved",
"timestamp": "2026-06-24T03:47:00Z",
"detail": "Monitor returned 200 OK"
}
]
}
}All errors return a JSON body with a code and a human-readable message.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "interval_seconds must be at least 60 on the Pro plan",
"field": "interval_seconds"
}
}| HTTP Status | Error Code | Meaning |
|---|---|---|
| 200 | — | Success |
| 201 | — | Resource created |
| 204 | — | Success, no response body (e.g. DELETE) |
| 400 | VALIDATION_ERROR | Invalid request body or query parameter |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key valid but lacks permission for this resource |
| 404 | NOT_FOUND | Resource does not exist or belongs to another account |
| 429 | RATE_LIMITED | Rate limit exceeded — retry after Retry-After seconds |
| 500 | INTERNAL_ERROR | Unexpected server error — contact support if it persists |
| Method | Endpoint | Description |
|---|---|---|
| GET | /monitors | List all monitors |
| POST | /monitors | Create a monitor |
| GET | /monitors/:id | Get a single monitor |
| PATCH | /monitors/:id | Update a monitor |
| DELETE | /monitors/:id | Delete a monitor |
| GET | /incidents | List incidents |
| GET | /incidents/:id | Get incident details |
| POST | /heartbeat/:id | Ping a heartbeat monitor |
Generate your API key from the Settings page. Available on Pro and higher plans.