SecurityBot API Documentation

The SecurityBot API provides programmatic access to your site's monitoring data, including uptime statistics, response times, and status codes.

Authentication

All API requests require authentication using an API key. You can generate and manage API keys from your site's settings page.

API Key Format

API keys follow the format: sb_ followed by 40 random characters.

Authentication Methods

Option 1: Bearer Token (Recommended)

Authorization: Bearer sb_your_api_key_here

Option 2: Custom Header

X-API-Key: sb_your_api_key_here

Rate Limiting

Limit: 10 requests per minute per API key
Headers: Rate limit information is included in response headers
Exceeded: Returns HTTP 429 status when limit is exceeded

Endpoints

GET /api/sites/{domain}/monitor

Retrieve monitoring data for a specific site.

Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	The domain name or site identifier
`start`	string	No	Start timestamp (ISO 8601 format)
`end`	string	No	End timestamp (ISO 8601 format)

Default Behavior

Returns the last 60 minutes of data when no time range is specified
Limited to 60 data points maximum per request
Data is returned in descending chronological order (newest first)

Example Request

curl -H "Authorization: Bearer sb_your_api_key_here" \
  "https://securitybot.dev/api/sites/example.com/monitor?start=2025-01-01T00:00:00Z&end=2025-01-01T23:59:59Z"

Response Format

{
  "site": {
    "name": "Example Site",
    "url": "https://example.com",
    "domain": "example.com"
  },
  "time_range": {
    "start": "2025-01-01T00:00:00.000000Z",
    "end": "2025-01-01T23:59:59.000000Z"
  },
  "aggregated_data": {
    "uptime_percentage": 99.5,
    "total_checks": 60,
    "online_checks": 59,
    "offline_checks": 1,
    "response_time": {
      "average_ms": 245.5,
      "minimum_ms": 120,
      "maximum_ms": 890
    },
    "status_codes": {
      "200": 58,
      "500": 1,
      "503": 1
    }
  },
  "raw_data": [
    {
      "timestamp": "2025-01-01T23:59:00.000000Z",
      "is_online": true,
      "response_time_ms": 234,
      "status_code": 200,
      "status_text": "OK",
      "error_message": null
    },
    {
      "timestamp": "2025-01-01T23:58:00.000000Z",
      "is_online": false,
      "response_time_ms": null,
      "status_code": 500,
      "status_text": "Internal Server Error",
      "error_message": "Connection timeout"
    }
  ],
  "pagination": {
    "total_available": 1440,
    "returned_count": 60,
    "has_more_data": true,
    "note": "Only the most recent 60 data points are returned. Use more specific time ranges for complete data."
  }
}

Response Fields

Site Information

site.name: Display name of the monitored site
site.url: Full URL of the monitored site
site.domain: Domain identifier used in the request

Time Range

time_range.start: Start of the queried time period (ISO 8601)
time_range.end: End of the queried time period (ISO 8601)

Aggregated Data

uptime_percentage: Overall uptime percentage for the time period
total_checks: Total number of monitoring checks performed
online_checks: Number of successful checks
offline_checks: Number of failed checks
response_time.average_ms: Average response time in milliseconds
response_time.minimum_ms: Fastest response time in the period
response_time.maximum_ms: Slowest response time in the period
status_codes: Distribution of HTTP status codes encountered

Raw Data Points

Each data point includes:

timestamp: When the check was performed (ISO 8601)
is_online: Boolean indicating if the site was accessible
response_time_ms: Response time in milliseconds (null if offline)
status_code: HTTP status code returned
status_text: Human-readable status description
error_message: Error details if the check failed

Pagination

total_available: Total number of data points in the time range
returned_count: Number of data points in this response
has_more_data: Boolean indicating if more data exists
note: Additional information about data limitations

Error Responses

401 Unauthorized

{
  "error": "API key required",
  "message": "Please provide an API key via Authorization: Bearer {key} header or X-API-Key header."
}

403 Forbidden

{
  "error": "API key mismatch",
  "message": "The API key does not have access to the requested site."
}

404 Not Found

{
  "error": "Site not found",
  "message": "No site found matching the provided domain."
}

400 Bad Request

{
  "error": "Invalid timestamp format",
  "message": "Please provide timestamps in ISO 8601 format (e.g., 2025-01-01T12:00:00Z)"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before making another request."
}

Best Practices

Time Range Queries

Use specific time ranges to get complete data sets
For large time ranges, consider making multiple requests
ISO 8601 format is required: 2025-01-01T12:00:00Z

Rate Limiting

Implement exponential backoff for rate limit handling
Monitor response headers for rate limit status
Cache responses when appropriate to reduce API calls

Error Handling

Always check HTTP status codes
Parse error messages for debugging information
Implement retry logic for temporary failures

Security

Keep API keys secure and never expose them in client-side code
Regenerate API keys if they may have been compromised
Use HTTPS for all API requests

Code Examples

Python

import requests
from datetime import datetime, timedelta

api_key = "sb_your_api_key_here"
domain = "example.com"
headers = {"Authorization": f"Bearer {api_key}"}

# Get last 60 minutes (default)
response = requests.get(
    f"https://securitybot.dev/api/sites/{domain}/monitor",
    headers=headers
)

# Get specific time range
start_time = (datetime.now() - timedelta(hours=24)).isoformat() + "Z"
end_time = datetime.now().isoformat() + "Z"

response = requests.get(
    f"https://securitybot.dev/api/sites/{domain}/monitor",
    headers=headers,
    params={"start": start_time, "end": end_time}
)

data = response.json()
print(f"Uptime: {data['aggregated_data']['uptime_percentage']}%")

JavaScript/Node.js

const axios = require('axios');

const apiKey = 'sb_your_api_key_here';
const domain = 'example.com';

const headers = {
  'Authorization': `Bearer ${apiKey}`
};

// Get monitoring data
async function getMonitoringData(domain, startTime = null, endTime = null) {
  try {
    const params = {};
    if (startTime) params.start = startTime;
    if (endTime) params.end = endTime;

    const response = await axios.get(
      `https://securitybot.dev/api/sites/${domain}/monitor`,
      { headers, params }
    );

    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
getMonitoringData('example.com')
  .then(data => {
    console.log(`Uptime: ${data.aggregated_data.uptime_percentage}%`);
    console.log(`Average response time: ${data.aggregated_data.response_time.average_ms}ms`);
  });

cURL

# Basic request
curl -H "Authorization: Bearer sb_your_api_key_here" \
  "https://securitybot.dev/api/sites/example.com/monitor"

# With time range
curl -H "Authorization: Bearer sb_your_api_key_here" \
  "https://securitybot.dev/api/sites/example.com/monitor?start=2025-01-01T00:00:00Z&end=2025-01-01T23:59:59Z"

# Using X-API-Key header
curl -H "X-API-Key: sb_your_api_key_here" \
  "https://securitybot.dev/api/sites/example.com/monitor"

Support

For additional help with the SecurityBot API:

Visit our Support Documentation
Contact us through the support page
Check the API settings page for your specific endpoint URLs

Changelog

Version 1.0 (Initial Release)

Basic monitoring data endpoint
API key authentication
Rate limiting (10 requests/minute)
Time range filtering
Aggregated statistics and raw data points