API Overview

The CuliUptime REST API provides programmatic access to all monitoring functionality. Build integrations, automate monitor management, and retrieve monitoring data using standard HTTP requests.

🚀 Quick Start

Base URL

• Cloud Service: https://uptime.culiops.net/api/v1
• Self-Hosted: https://your-domain.com/api/v1

Authentication

All API requests require authentication using Bearer tokens:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://uptime.culiops.net/api/v1/monitors

First API Call

API calls require authenticated session through OAuth2. Use the web dashboard for authentication:

# Example: Get all monitors (requires authenticated session)
curl -X GET \
  -H "Content-Type: application/json" \
  -b "session_cookie=YOUR_SESSION" \
  https://uptime.culiops.net/api/v1/monitors

🔐 Authentication

CuliUptime uses OAuth2 social login with Google and GitHub. API access requires authenticated sessions through the web application.

OAuth2 Providers

• Google OAuth2: Sign in with Google account
• GitHub OAuth2: Sign in with GitHub account

Authentication Flow

1. Navigate to CuliUptime dashboard
2. Click "Sign in with Google" or "Sign in with GitHub"
3. Complete OAuth2 authorization
4. Access API endpoints through authenticated session
5. Use refresh tokens for session management

Security Features

• Secure OAuth2 implementation with Authlib
• Session-based authentication
• Automatic token refresh
• HTTPS enforcement
• CORS protection

📊 Core Concepts

Resources

The API is organized around these main resources:

• Monitors - HTTP/HTTPS monitoring configurations and results
• Agents - Global PHP-based monitoring agent network
• Notifications - Email alert history and management
• Auth - OAuth2 authentication (Google, GitHub)
• Dashboard - Real-time monitoring dashboard data
• Preferences - User account settings and preferences

HTTP Methods

• GET - Retrieve resources
• POST - Create new resources
• PUT - Update/replace resources
• PATCH - Partial resource updates
• DELETE - Remove resources

Response Format

All responses use JSON format:

{
  "data": {
    "id": 123,
    "name": "My Website",
    "url": "https://example.com",
    "status": "online"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "URL is required",
    "details": {
      "field": "url",
      "value": null
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

🔗 Endpoints Overview

Authentication

Method	Endpoint	Description
GET	/auth/google/login	Initiate Google OAuth2 login
GET	/auth/google/callback	Handle Google OAuth2 callback
GET	/auth/github/login	Initiate GitHub OAuth2 login
GET	/auth/github/callback	Handle GitHub OAuth2 callback
POST	/auth/refresh	Refresh access token
GET	/auth/user	Get current authenticated user
POST	/auth/logout	Logout user session

Monitors

Method	Endpoint	Description
GET	/monitors	List monitors with pagination/filtering
POST	/monitors	Create new HTTP/HTTPS monitor
GET	/monitors/{id}	Get monitor details
PUT	/monitors/{id}	Update monitor configuration
PATCH	/monitors/{id}	Partially update monitor
DELETE	/monitors/{id}	Delete monitor
POST	/monitors/{id}/enable	Enable monitor
POST	/monitors/{id}/disable	Disable monitor
POST	/monitors/{id}/test	Test monitor immediately
GET	/monitors/{id}/results	Get monitoring results history
GET	/monitors/{id}/stats	Get monitor statistics
POST	/monitors/{id}/agents	Assign agents to monitor
GET	/monitors/{id}/agents	List monitor's assigned agents
DELETE	/monitors/{id}/agents	Remove agents from monitor

Agents

Method	Endpoint	Description
GET	/agents	List all agents
POST	/agents	Create new monitoring agent
GET	/agents/accessible	List user-accessible agents
GET	/agents/stats	Get global agent statistics
GET	/agents/{id}	Get agent details
PUT	/agents/{id}	Update agent configuration
PATCH	/agents/{id}/status	Update agent status
POST	/agents/{id}/validate	Validate agent connectivity
GET	/agents/{id}/credentials	Get agent credentials
DELETE	/agents/{id}	Delete agent
PATCH	/agents/{id}/toggle-publishing	Toggle agent public availability

Notifications

Method	Endpoint	Description
GET	/notifications/active	Get active notifications
GET	/notifications/recent	Get recent notifications
GET	/notifications	List notification history
GET	/notifications/{id}	Get notification details
POST	/notifications/{id}/acknowledge	Acknowledge notification
POST	/notifications/{id}/resolve	Resolve notification

Dashboard

Method	Endpoint	Description
GET	/dashboard	Get dashboard overview data

User Preferences

Method	Endpoint	Description
GET	/preferences	Get user preferences
PUT	/preferences	Update user preferences

📖 Common Use Cases

1. Monitor Management

# Create a new monitor
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expected_status": [200],
    "check_interval": 300,
    "timeout": 30
  }' \
  https://uptime.culiops.net/api/v1/monitors

2. Status Dashboard

# Get status of all monitors
curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://uptime.culiops.net/api/v1/monitors?status=true&uptime=true"

3. Alert Integration

# Get recent alerts
curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://uptime.culiops.net/api/v1/alerts?since=2024-01-01&limit=50"

4. Bulk Operations

# Pause multiple monitors
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor_ids": [1, 2, 3, 4],
    "action": "pause",
    "reason": "Scheduled maintenance"
  }' \
  https://uptime.culiops.net/api/v1/monitors/bulk

🔄 Pagination

Large result sets are paginated:

# Get first page (default)
curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://uptime.culiops.net/api/v1/monitors?page=1&limit=25"

# Response includes pagination info
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "pages": 6,
    "has_next": true,
    "has_prev": false
  }
}

🔍 Filtering & Search

Query Parameters

• status - Filter by monitor status (online, offline, warning)
• search - Search monitor names and URLs
• tags - Filter by tags
• created_after - Filter by creation date
• updated_since - Filter by last update

Examples

# Search monitors (requires authenticated session)
curl -X GET \
  -b "session_cookie=YOUR_SESSION" \
  "https://uptime.culiops.net/api/v1/monitors?search=api&status=online"

# Get recent notifications
curl -X GET \
  -b "session_cookie=YOUR_SESSION" \
  "https://uptime.culiops.net/api/v1/notifications/recent"

📊 Data Formats

Monitor Object

{
  "id": 123,
  "name": "My Website",
  "url": "https://example.com",
  "method": "GET",
  "expected_status": [200, 201],
  "check_interval": 300,
  "timeout": 30,
  "status": "online",
  "last_check": "2024-01-15T10:30:00Z",
  "uptime_24h": 99.95,
  "response_time": 245,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T08:15:00Z"
}

Notification Object

{
  "id": 456,
  "monitor_id": 123,
  "type": "downtime",
  "message": "Monitor 'My Website' is offline",
  "status": "resolved",
  "started_at": "2024-01-15T10:00:00Z",
  "resolved_at": "2024-01-15T10:05:00Z",
  "duration": 300,
  "acknowledged": true,
  "notification_method": "email"
}

⚡ Rate Limits

Current Limits

• Free accounts: 1,000 requests/hour
• Self-hosted: No limits (configurable)

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200

Handling Rate Limits

import requests
import time

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            # Rate limited, wait and retry
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

🔒 Security

HTTPS Only

All API endpoints require HTTPS. HTTP requests are automatically redirected.

Input Validation

All inputs are validated and sanitized. Invalid requests return detailed error messages.

CORS Support

Cross-origin requests are supported with proper configuration.

🛠️ Development Tools

Interactive API Explorer

• Cloud: https://uptime.culiops.net/docs
• Self-hosted: https://your-domain.com/docs

OpenAPI Specification

• JSON: https://uptime.culiops.net/openapi.json
• YAML: https://uptime.culiops.net/openapi.yaml

SDKs and Libraries

Official SDKs available for:

• Python - pip install culiuptime-python
• JavaScript/Node.js - npm install culiuptime-js
• PHP - composer require culiuptime/php-sdk
• Go - go get github.com/chiplonton/culiuptime-go

🐛 Error Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created
400	Bad Request	Invalid request data
401	Unauthorized	Invalid or missing token
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource already exists
429	Rate Limited	Too many requests
500	Internal Error	Server error

📚 Code Examples

Ready to dive deeper? Check out detailed examples:

• cURL Examples - Command-line usage
• Python Examples - Python integration
• JavaScript Examples - Web and Node.js
• PHP Examples - PHP integration

🚀 Next Steps

1. Generate an API token to get started
2. Explore endpoints for detailed documentation
3. Try the interactive docs for hands-on testing
4. Download an SDK for your preferred language

The CuliUptime API is designed to be powerful yet simple to use. Start with basic monitor management and expand to build custom integrations! 🎯