🔌 Grim Reaper API Documentation

Complete reference for the Grim Reaper REST API - Programmatic access to the unified data protection ecosystem

v1.0.0 Production Ready

🔐 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

200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Rate Limited
500 Internal Server Error

💾 Backup Management

Create, manage, and monitor backup operations programmatically.

Create Backup

POST /api/backup/create

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

GET /api/backup/{backup_id}

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

GET /api/backup/list

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

POST /api/restore/create

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 /api/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 /api/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

GET /api/user/profile

Retrieve the current user's profile information.

Update User Profile

PUT /api/user/profile

Update the current user's profile information.

Change Password

POST /api/user/change-password

Change the current user's password.

⚔️ Scythe License API

Manage software licenses and protection through the Scythe platform.

Generate License

POST /api/scythe/license/generate

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

POST /api/scythe/license/validate

Validate a software license key.

🔗 Webhook Integration

Configure webhooks to receive real-time notifications about backup events.

Create Webhook

POST /api/webhook/create

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 started
  • backup.completed - Backup operation completed successfully
  • backup.failed - Backup operation failed
  • restore.started - Restore operation started
  • restore.completed - Restore operation completed
  • restore.failed - Restore operation failed
  • system.alert - System alert or warning

📈 Analytics & Reporting

Access analytics data and generate reports programmatically.

Backup Analytics

GET /api/analytics/backups

Get backup analytics and trends.

Storage Analytics

GET /api/analytics/storage

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.