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 name
url (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 monitors
resume - Resume multiple monitors
delete - Delete multiple monitors
update - 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 exist
INVALID_MONITOR_TYPE - Unsupported monitor type
RATE_LIMIT_EXCEEDED - Too many API requests
INSUFFICIENT_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! 🚀

📋 Monitor Object​

📝 Endpoints​

List Monitors​

Get Monitor​

Create Monitor​

Update Monitor​

Delete Monitor​

Pause Monitor​

Resume Monitor​

Test Monitor​

📊 Monitor Statistics​

Get Monitor Statistics​

Get Monitor History​

🔔 Monitor Alerts​

Get Monitor Alerts​

Update Monitor Alert Settings​

🌐 Bulk Operations​

Bulk Monitor Actions​

📋 Monitor Types & Configuration​

HTTP/HTTPS Monitors​

Future Monitor Types (v0.2.0+)​

❌ Error Responses​

Validation Errors​

Common Error Codes​

🚀 Best Practices​

Monitor Naming​

Check Intervals​

Timeout Values​

Location Strategy​

📋 Monitor Object

📝 Endpoints

List Monitors

Get Monitor

Create Monitor

Update Monitor

Delete Monitor

Pause Monitor

Resume Monitor

Test Monitor

📊 Monitor Statistics

Get Monitor Statistics

Get Monitor History

🔔 Monitor Alerts

Get Monitor Alerts

Update Monitor Alert Settings

🌐 Bulk Operations

Bulk Monitor Actions

📋 Monitor Types & Configuration

HTTP/HTTPS Monitors

Future Monitor Types (v0.2.0+)

❌ Error Responses

Validation Errors

Common Error Codes

🚀 Best Practices

Monitor Naming

Check Intervals

Timeout Values

Location Strategy