Grim Reaper API Documentation

Complete guide to integrating with the Grim Reaper data protection platform

v2.0.0 Stable

Getting Started

Core APIs

SDKs & Libraries

Authentication

All API requests require authentication using API keys. Include your API key in the request headers.

API Key Authentication 
curl -X GET "https://api.grim.so/v2/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

🔑 Getting Your API Key

1. Log into your Grim Reaper dashboard

2. Navigate to Account → API Keys

3. Generate a new API key

4. Keep your API key secure and never share it publicly

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

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

Common Error Codes

400

Bad Request

Invalid request parameters or malformed JSON

401

Unauthorized

Invalid or missing API key

403

Forbidden

Insufficient permissions for the requested resource

404

Not Found

Requested resource does not exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Unexpected server error

Error Response Example 
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'backup_id' parameter is required",
    "details": {
      "parameter": "backup_id",
      "type": "required"
    }
  },
  "request_id": "req_1234567890abcdef"
}

Backup Management API

Create, manage, and monitor your data backups programmatically.

Create Backup

POST /v2/backups

Create a new backup of specified data sources.

Request Example 
curl -X POST "https://api.grim.so/v2/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Database Backup",
    "sources": [
      {
        "type": "database",
        "connection": {
          "host": "localhost",
          "port": 5432,
          "database": "myapp",
          "username": "backup_user"
        }
      }
    ],
    "schedule": {
      "frequency": "daily",
      "time": "02:00"
    },
    "retention": {
      "days": 30,
      "copies": 5
    }
  }'

Response

{
  "backup": {
    "id": "backup_1234567890abcdef",
    "name": "Daily Database Backup",
    "status": "scheduled",
    "created_at": "2024-01-15T10:30:00Z",
    "next_run": "2024-01-16T02:00:00Z",
    "sources": [...],
    "schedule": {...},
    "retention": {...}
  }
}

List Backups

GET /v2/backups

Retrieve a list of all backups for your account.

Query Parameters

Parameter Type Required Description
limit integer No Number of backups to return (default: 20, max: 100)
offset integer No Number of backups to skip (default: 0)
status string No Filter by status (scheduled, running, completed, failed)
created_after string No Filter backups created after this date (ISO 8601)

Get Backup Details

GET /v2/backups/{backup_id}

Retrieve detailed information about a specific backup.

Update Backup

PUT /v2/backups/{backup_id}

Update backup configuration and settings.

Delete Backup

DELETE /v2/backups/{backup_id}

Delete a backup and all associated data.

Storage Management API

Manage storage allocation, monitor usage, and configure storage policies.

Get Storage Usage

GET /v2/storage/usage

Retrieve current storage usage statistics.

Response

{
  "usage": {
    "total_allocated": "100GB",
    "total_used": "45.2GB",
    "total_available": "54.8GB",
    "usage_percentage": 45.2,
    "breakdown": {
      "backups": "23.4GB",
      "snapshots": "15.8GB",
      "archives": "6.0GB"
    },
    "last_updated": "2024-01-15T10:30:00Z"
  }
}

Get Storage Policies

GET /v2/storage/policies

Retrieve storage policies and configuration.

Update Storage Policy

PUT /v2/storage/policies/{policy_id}

Update storage policy configuration.

Monitoring & Analytics API

Monitor system performance, track metrics, and analyze backup patterns.

Get System Metrics

GET /v2/metrics/system

Retrieve system performance metrics.

Query Parameters

Parameter Type Required Description
timeframe string No Time range (1h, 24h, 7d, 30d)
metrics string No Comma-separated list of metrics to include

Get Backup Analytics

GET /v2/analytics/backups

Retrieve backup performance analytics and trends.

Get API Usage

GET /v2/analytics/api-usage

Retrieve API usage statistics and trends.

Security & Encryption API

Manage encryption keys, security policies, and access controls.

Get Encryption Keys

GET /v2/security/keys

Retrieve encryption key information (metadata only).

Rotate Encryption Key

POST /v2/security/keys/rotate

Rotate encryption keys for enhanced security.

Get Security Policies

GET /v2/security/policies

Retrieve security policies and configuration.

Webhooks

Receive real-time notifications about backup events and system changes.

Supported Events

backup.started

Triggered when a backup job starts

backup.completed

Triggered when a backup job completes successfully

backup.failed

Triggered when a backup job fails

storage.threshold

Triggered when storage usage exceeds threshold

security.alert

Triggered when security events occur

Webhook Payload Example 
{
  "event": "backup.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "backup_id": "backup_1234567890abcdef",
    "name": "Daily Database Backup",
    "size": "2.3GB",
    "duration": 180,
    "status": "completed"
  },
  "signature": "sha256=abc123..."
}

Python SDK

Official Python SDK for easy integration with Grim Reaper APIs.

Installation

Install via pip 
pip install grim-reaper-sdk

Quick Start

Python Example 
from grim_reaper import GrimReaper

# Initialize client
client = GrimReaper(api_key="YOUR_API_KEY")

# Create a backup
backup = client.backups.create(
    name="My Database Backup",
    sources=[{
        "type": "database",
        "connection": {
            "host": "localhost",
            "database": "myapp"
        }
    }]
)

# List backups
backups = client.backups.list(limit=10)

# Get backup details
backup_details = client.backups.get(backup.id)

# Monitor storage usage
usage = client.storage.get_usage()
print(f"Used: {usage.total_used} of {usage.total_allocated}")

JavaScript SDK

Official JavaScript/Node.js SDK for web and server applications.

Installation

Install via npm 
npm install @grim-reaper/sdk

Quick Start

JavaScript Example 
const { GrimReaper } = require('@grim-reaper/sdk');

// Initialize client
const client = new GrimReaper({
  apiKey: 'YOUR_API_KEY'
});

// Create a backup
const backup = await client.backups.create({
  name: 'My Database Backup',
  sources: [{
    type: 'database',
    connection: {
      host: 'localhost',
      database: 'myapp'
    }
  }]
});

// List backups
const backups = await client.backups.list({ limit: 10 });

// Get storage usage
const usage = await client.storage.getUsage();
console.log(`Used: ${usage.totalUsed} of ${usage.totalAllocated}`);

Postman Collection

Import our Postman collection to test APIs directly in your browser.

📥 Download Postman Collection

Import this collection into Postman to get started quickly with all API endpoints.

Need Help?

📚 Documentation

Browse our comprehensive guides and tutorials

View Documentation

💬 Community

Join our community forum for discussions

Join Community

🎫 Support

Get help from our support team

Contact Support