# 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
```bash
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
```json
{
"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
```json
{
"error": "API key required",
"message": "Please provide an API key via Authorization: Bearer {key} header or X-API-Key header."
}
```
### 403 Forbidden
```json
{
"error": "API key mismatch",
"message": "The API key does not have access to the requested site."
}
```
### 404 Not Found
```json
{
"error": "Site not found",
"message": "No site found matching the provided domain."
}
```
### 400 Bad Request
```json
{
"error": "Invalid timestamp format",
"message": "Please provide timestamps in ISO 8601 format (e.g., 2025-01-01T12:00:00Z)"
}
```
### 429 Too Many Requests
```json
{
"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
```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
```javascript
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
```bash
# 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](https://securitybot.dev/support)
- 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