🔌 Grim Reaper API Documentation
Complete reference for the Grim Reaper REST API - Programmatic access to the unified data protection ecosystem
🔐 Authentication
All API requests require authentication using API keys or OAuth 2.0 tokens.
API Key Authentication
Include your API key in the request headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Get your API key: Navigate to Admin → License Manager → Generate API Key
OAuth 2.0 Authentication
For advanced integrations, use OAuth 2.0:
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
OAuth endpoints:
- Authorization:
/oauth/authorize
- Token:
/oauth/token
- Refresh:
/oauth/refresh
⚡ Rate Limits
API requests are rate-limited to ensure fair usage and system stability.
Plan | Requests per Minute | Requests per Hour | Requests per Day |
---|---|---|---|
FREE | 60 | 1,000 | 10,000 |
PRO | 300 | 10,000 | 100,000 |
MASTER | 1,000 | 50,000 | 500,000 |
REAPER | Unlimited | Unlimited | Unlimited |
Rate Limit Headers
Response headers include rate limit information:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640995200
⚠️ Error Handling
All API errors follow a consistent format with appropriate HTTP status codes.
Error Response Format
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid or expired",
"details": {
"field": "authorization",
"suggestion": "Please check your API key and try again"
},
"timestamp": "2024-01-01T12:00:00Z",
"request_id": "req_123456789"
}
}
Common HTTP Status Codes
💾 Backup Management
Create, manage, and monitor backup operations programmatically.
Create Backup
Initiate a new backup operation for specified sources.
Request Body
{
"sources": [
{
"type": "database",
"connection": {
"host": "localhost",
"port": 5432,
"database": "myapp",
"username": "user",
"password": "password"
}
},
{
"type": "filesystem",
"paths": ["/var/www/html", "/etc/nginx"],
"exclude": ["*.tmp", "*.log"]
}
],
"options": {
"compression": "gzip",
"encryption": true,
"retention_days": 30,
"notify_on_completion": true
}
}
Response
{
"success": true,
"backup_id": "backup_123456789",
"status": "queued",
"estimated_duration": "5 minutes",
"created_at": "2024-01-01T12:00:00Z"
}
Get Backup Status
Retrieve the current status and details of a backup operation.
Response
{
"success": true,
"backup": {
"id": "backup_123456789",
"status": "completed",
"progress": 100,
"size_bytes": 1073741824,
"sources": [
{
"type": "database",
"name": "myapp",
"size_bytes": 536870912,
"status": "completed"
},
{
"type": "filesystem",
"name": "web_files",
"size_bytes": 536870912,
"status": "completed"
}
],
"created_at": "2024-01-01T12:00:00Z",
"completed_at": "2024-01-01T12:05:00Z",
"duration_seconds": 300
}
}
List Backups
Retrieve a list of all backups with optional filtering.
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
status | string | No | Filter by status (queued, running, completed, failed) |
limit | integer | No | Number of results to return (default: 50, max: 100) |
offset | integer | No | Number of results to skip for pagination |
created_after | datetime | No | Filter backups created after this date |
🔄 Restore Operations
Restore data from backups to original or new locations.
Create Restore
Initiate a restore operation from a backup.
Request Body
{
"backup_id": "backup_123456789",
"targets": [
{
"type": "database",
"connection": {
"host": "localhost",
"port": 5432,
"database": "myapp_restored",
"username": "user",
"password": "password"
},
"options": {
"drop_existing": true,
"preserve_permissions": true
}
},
{
"type": "filesystem",
"path": "/var/www/html_restored",
"options": {
"overwrite_existing": false,
"preserve_timestamps": true
}
}
],
"options": {
"validate_checksums": true,
"notify_on_completion": true
}
}
📊 System Monitoring
Monitor system health, performance, and resource usage.
System Status
Get overall system status and health information.
Response
{
"status": "operational",
"timestamp": "2024-01-01T12:00:00Z",
"version": "1.0.0",
"components": {
"database": "healthy",
"storage": "healthy",
"api": "healthy",
"scheduler": "healthy"
},
"metrics": {
"uptime_seconds": 86400,
"active_backups": 5,
"storage_used_gb": 150.5,
"storage_total_gb": 1000.0
}
}
Usage Metrics
Get detailed usage metrics and statistics.
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
range | string | No | Time range (24h, 7d, 30d, 90d) |
👤 User Management
Manage user accounts, profiles, and preferences.
Get User Profile
Retrieve the current user's profile information.
Update User Profile
Update the current user's profile information.
Change Password
Change the current user's password.
⚔️ Scythe License API
Manage software licenses and protection through the Scythe platform.
Generate License
Generate a new software license key.
Request Body
{
"product_id": "prod_123",
"license_type": "perpetual",
"customer_name": "John Doe",
"customer_email": "john@example.com",
"company_name": "Acme Corp",
"features": ["feature1", "feature2"],
"expiry_date": "2025-01-01",
"max_users": 10
}
Validate License
Validate a software license key.
🔗 Webhook Integration
Configure webhooks to receive real-time notifications about backup events.
Create Webhook
Create a new webhook endpoint.
Request Body
{
"url": "https://your-app.com/webhook",
"events": ["backup.completed", "backup.failed", "restore.completed"],
"secret": "your_webhook_secret",
"description": "Production backup notifications"
}
Webhook Events
Available webhook events:
backup.started
- Backup operation startedbackup.completed
- Backup operation completed successfullybackup.failed
- Backup operation failedrestore.started
- Restore operation startedrestore.completed
- Restore operation completedrestore.failed
- Restore operation failedsystem.alert
- System alert or warning
📈 Analytics & Reporting
Access analytics data and generate reports programmatically.
Backup Analytics
Get backup analytics and trends.
Storage Analytics
Get storage usage analytics.
🔧 SDK Examples
Code examples for integrating with the Grim Reaper API in various programming languages.
Python
import requests
class GrimReaperAPI:
def __init__(self, api_key, base_url="https://api.grim.so"):
self.api_key = api_key
self.base_url = base_url
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
def create_backup(self, sources, options=None):
url = f"{self.base_url}/api/backup/create"
data = {"sources": sources}
if options:
data["options"] = options
response = requests.post(url, json=data, headers=self.headers)
return response.json()
def get_backup_status(self, backup_id):
url = f"{self.base_url}/api/backup/{backup_id}"
response = requests.get(url, headers=self.headers)
return response.json()
# Usage example
api = GrimReaperAPI("your_api_key")
backup = api.create_backup([
{
"type": "database",
"connection": {
"host": "localhost",
"database": "myapp",
"username": "user",
"password": "password"
}
}
])
print(f"Backup ID: {backup['backup_id']}")
JavaScript/Node.js
class GrimReaperAPI {
constructor(apiKey, baseUrl = 'https://api.grim.so') {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
this.headers = {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
};
}
async createBackup(sources, options = {}) {
const url = `${this.baseUrl}/api/backup/create`;
const data = { sources, ...(options && { options }) };
const response = await fetch(url, {
method: 'POST',
headers: this.headers,
body: JSON.stringify(data)
});
return response.json();
}
async getBackupStatus(backupId) {
const url = `${this.baseUrl}/api/backup/${backupId}`;
const response = await fetch(url, {
headers: this.headers
});
return response.json();
}
}
// Usage example
const api = new GrimReaperAPI('your_api_key');
api.createBackup([
{
type: 'database',
connection: {
host: 'localhost',
database: 'myapp',
username: 'user',
password: 'password'
}
}
]).then(backup => {
console.log(`Backup ID: ${backup.backup_id}`);
});
cURL
# Create a backup
curl -X POST https://api.grim.so/api/backup/create \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{
"type": "database",
"connection": {
"host": "localhost",
"database": "myapp",
"username": "user",
"password": "password"
}
}
]
}'
# Get backup status
curl -X GET https://api.grim.so/api/backup/backup_123456789 \
-H "Authorization: Bearer YOUR_API_KEY"
# Get system status
curl -X GET https://api.grim.so/api/status \
-H "Authorization: Bearer YOUR_API_KEY"
❓ Frequently Asked Questions
How do I get an API key?
Navigate to the Admin Dashboard → License Manager → Generate API Key. You can create multiple API keys for different applications.
What's the difference between API keys and OAuth tokens?
API keys are simple authentication tokens that don't expire. OAuth tokens provide more security features like expiration and scope limitations.
How do I handle rate limiting?
Monitor the rate limit headers in API responses and implement exponential backoff when approaching limits. Consider upgrading your plan for higher limits.
Can I use webhooks for real-time notifications?
Yes! Configure webhooks to receive real-time notifications about backup events, system alerts, and other important activities.
How do I validate webhook signatures?
Webhook requests include a signature header that you can validate using your webhook secret to ensure authenticity.