Monitors API
Complete reference for managing monitors via the CuliUptime REST API. Create, read, update, and delete monitors programmatically.
📋 Monitor Object
{
"id": 123,
"name": "My Website",
"url": "https://example.com",
"type": "http",
"method": "GET",
"expected_status": [200, 201],
"timeout": 30,
"check_interval": 300,
"retry_count": 3,
"locations": ["us-east", "eu-west"],
"status": "online",
"uptime_24h": 99.95,
"uptime_7d": 99.87,
"uptime_30d": 99.92,
"response_time": 245,
"last_check": "2024-01-15T10:30:00Z",
"last_success": "2024-01-15T10:30:00Z",
"last_failure": "2024-01-14T08:15:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T08:00:00Z"
}
📝 Endpoints
List Monitors
Get all monitors for the authenticated user.
Request:
GET /api/v1/monitors
Parameters:
Parameter | Type | Description |
---|---|---|
page | integer | Page number (default: 1) |
limit | integer | Results per page (max: 100, default: 25) |
status | string | Filter by status: online , offline , warning |
search | string | Search monitor names and URLs |
type | string | Filter by type: http , https |
Example:
curl -X GET \
-b "session_cookie=YOUR_SESSION" \
"https://uptime.culiops.net/api/v1/monitors?status=online&limit=50"
Response:
{
"data": [
{
"id": 123,
"name": "My Website",
"url": "https://example.com",
"status": "online",
"uptime_24h": 99.95
}
],
"pagination": {
"page": 1,
"limit": 25,
"total": 150,
"pages": 6
}
}
Get Monitor
Retrieve details for a specific monitor.
Request:
GET /api/v1/monitors/{id}
Example:
curl -X GET \
-b "session_cookie=YOUR_SESSION" \
https://uptime.culiops.net/api/v1/monitors/123
Response:
{
"data": {
"id": 123,
"name": "My Website",
"url": "https://example.com",
"type": "http",
"method": "GET",
"expected_status": [200],
"timeout": 30,
"check_interval": 300,
"status": "online",
"uptime_24h": 99.95,
"response_time": 245,
"created_at": "2024-01-01T00:00:00Z"
}
}
Create Monitor
Create a new monitor.
Request:
POST /api/v1/monitors
Required Fields:
name
(string): Monitor nameurl
(string): URL to monitor (for HTTP monitors)type
(string): Monitor type (http
,tcp
,ping
,dns
)
Example - HTTP Monitor:
curl -X POST \
-b "session_cookie=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"name": "My API Endpoint",
"url": "https://api.example.com/health",
"type": "http",
"method": "GET",
"expected_status": [200, 201],
"timeout": 30,
"check_interval": 300,
"retry_count": 3,
"locations": ["us-east", "eu-west"]
}' \
https://uptime.culiops.net/api/v1/monitors
Note: TCP, UDP, ICMP ping, and DNS monitoring are planned for CuliUptime v0.2.0+. The current v0.1.0 MVP supports HTTP/HTTPS monitoring only.
Response:
{
"data": {
"id": 124,
"name": "My API Endpoint",
"url": "https://api.example.com/health",
"type": "http",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z"
}
}
Update Monitor
Update an existing monitor.
Request:
PUT /api/v1/monitors/{id}
Example:
curl -X PUT \
-b "session_cookie=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Monitor Name",
"check_interval": 600,
"timeout": 45
}' \
https://uptime.culiops.net/api/v1/monitors/123
Delete Monitor
Delete a monitor permanently.
Request:
DELETE /api/v1/monitors/{id}
Example:
curl -X DELETE \
-b "session_cookie=YOUR_SESSION" \
https://uptime.culiops.net/api/v1/monitors/123
Response:
{
"message": "Monitor deleted successfully"
}
Pause Monitor
Temporarily disable monitoring.
Request:
POST /api/v1/monitors/{id}/pause
Example:
curl -X POST \
-b "session_cookie=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{"reason": "Scheduled maintenance"}' \
https://uptime.culiops.net/api/v1/monitors/123/pause
Resume Monitor
Resume monitoring after pausing.
Request:
POST /api/v1/monitors/{id}/resume
Example:
curl -X POST \
-b "session_cookie=YOUR_SESSION" \
https://uptime.culiops.net/api/v1/monitors/123/resume
Test Monitor
Run an immediate check on a monitor.
Request:
POST /api/v1/monitors/{id}/test
Example:
curl -X POST \
-b "session_cookie=YOUR_SESSION" \
https://uptime.culiops.net/api/v1/monitors/123/test
Response:
{
"data": {
"status": "online",
"response_time": 234,
"status_code": 200,
"checked_at": "2024-01-15T10:35:00Z",
"error": null
}
}
📊 Monitor Statistics
Get Monitor Statistics
Retrieve detailed statistics for a monitor.
Request:
GET /api/v1/monitors/{id}/stats
Parameters:
Parameter | Type | Description |
---|---|---|
period | string | Time period: 24h , 7d , 30d , 90d |
granularity | string | Data granularity: 5m , 1h , 1d |
Example:
curl -X GET \
-b "session_cookie=YOUR_SESSION" \
"https://uptime.culiops.net/api/v1/monitors/123/stats?period=7d&granularity=1h"
Response:
{
"data": {
"uptime": {
"24h": 99.95,
"7d": 99.87,
"30d": 99.92
},
"response_times": {
"avg": 245,
"min": 89,
"max": 1200,
"p95": 450
},
"incidents": {
"count": 2,
"total_downtime": 1800
},
"checks": {
"total": 2016,
"successful": 2014,
"failed": 2
}
}
}
Get Monitor History
Retrieve check history for a monitor.
Request:
GET /api/v1/monitors/{id}/history
Parameters:
Parameter | Type | Description |
---|---|---|
from | string | Start date (ISO 8601) |
to | string | End date (ISO 8601) |
limit | integer | Max results (default: 100) |
Example:
curl -X GET \
-b "session_cookie=YOUR_SESSION" \
"https://uptime.culiops.net/api/v1/monitors/123/history?from=2024-01-01T00:00:00Z&limit=50"
🔔 Monitor Alerts
Get Monitor Alerts
Retrieve alerts for a specific monitor.
Request:
GET /api/v1/monitors/{id}/alerts
Example:
curl -X GET \
-b "session_cookie=YOUR_SESSION" \
https://uptime.culiops.net/api/v1/monitors/123/alerts
Update Monitor Alert Settings
Configure alert settings for a monitor.
Request:
PUT /api/v1/monitors/{id}/alerts
Example:
curl -X PUT \
-b "session_cookie=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"email_enabled": true,
"email_recipients": ["[email protected]"],
"slack_enabled": false,
"alert_on_recovery": true,
"alert_threshold": 2
}' \
https://uptime.culiops.net/api/v1/monitors/123/alerts
🌐 Bulk Operations
Bulk Monitor Actions
Perform actions on multiple monitors at once.
Request:
POST /api/v1/monitors/bulk
Example - Bulk Pause:
curl -X POST \
-b "session_cookie=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"action": "pause",
"monitor_ids": [123, 124, 125],
"reason": "Scheduled maintenance window"
}' \
https://uptime.culiops.net/api/v1/monitors/bulk
Supported Actions:
pause
- Pause multiple monitorsresume
- Resume multiple monitorsdelete
- Delete multiple monitorsupdate
- Apply same settings to multiple monitors
📋 Monitor Types & Configuration
HTTP/HTTPS Monitors
{
"name": "Website Monitor",
"type": "http",
"url": "https://example.com",
"method": "GET",
"expected_status": [200, 201, 204],
"timeout": 30,
"follow_redirects": true,
"verify_ssl": true,
"headers": {
"User-Agent": "CuliUptime-Monitor/1.0",
"Authorization": "Bearer token123"
},
"body": "{\"health\": \"check\"}",
"expected_content": "status: ok",
"excluded_content": "error",
"json_path": "$.status",
"expected_json_value": "healthy"
}
Future Monitor Types (v0.2.0+)
The following monitor types are planned for future releases:
- TCP Monitors: Check if TCP ports are accessible
- ICMP Ping Monitors: Test network connectivity via ping
- DNS Monitors: Verify DNS resolution and record values
- UDP Monitors: Monitor UDP-based services
Stay tuned for these features in upcoming CuliUptime releases!
❌ Error Responses
Validation Errors
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid monitor configuration",
"details": {
"url": ["URL is required for HTTP monitors"],
"timeout": ["Timeout must be between 5 and 300 seconds"]
}
}
}
Common Error Codes
MONITOR_NOT_FOUND
- Monitor with specified ID doesn't existINVALID_MONITOR_TYPE
- Unsupported monitor typeRATE_LIMIT_EXCEEDED
- Too many API requestsINSUFFICIENT_PERMISSIONS
- Token lacks required permissions
🚀 Best Practices
Monitor Naming
- Use descriptive, searchable names
- Include environment (prod, staging, dev)
- Group related monitors with prefixes
Check Intervals
- Critical services: 1-2 minutes
- Important services: 5 minutes
- Non-critical services: 15-30 minutes
Timeout Values
- Web pages: 30-60 seconds
- APIs: 10-30 seconds
- Health endpoints: 5-15 seconds
Location Strategy
- Use multiple locations for critical services
- Choose locations close to your users
- Consider consensus checking to reduce false positives
Ready to monitor everything? Start with the Authentication guide to get your API token! 🚀