NebulaProof - Cryptographic Proof Storage Platform

Authentication

Bearer Token Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN_HERE

Token Security

Access tokens expire after 15 minutes. Use the refresh token endpoint to get a new access token.

Getting Your API Token

1.Log in to your account via /auth/login
2.Copy the access_token from the response
3.Include it in the Authorization header of all subsequent requests

Rate Limits

100

req/min

Starter

1,000

req/min

Professional

Custom

Contact sales

Enterprise

Rate limit headers are included in all responses:

• X-RateLimit-Limit - Total requests allowed per window
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when the limit resets

Error Codes

Code	Meaning
200	OK - Request successful
201	Created - Resource created successfully
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Authentication Endpoints

POST

/auth/login

Authenticate user and receive access token

Request Body:

{
  "email": "dev@example.com",
  "password": "password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_abc123xyz...",
  "token_type": "bearer",
  "expires_in": 900,
  "refresh_expires_in": 604800,
  "user": {
    "id": "user-123",
    "email": "dev@example.com",
    "role": "user",
    "tier": "professional"
  }
}

POST

/api/v1/auth/signup

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123!@#",
  "company_name": "Acme Corp",
  "tier": "trial"
}

Response:

{
  "success": true,
  "user_id": "user-456",
  "email": "user@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "organization_id": "org-789",
  "tier": "trial",
  "role": "user"
}

POST

/auth/refresh

Refresh access token using refresh token

Request Body:

{
  "refresh_token": "refresh_abc123xyz..."
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_def456uvw...",
  "token_type": "bearer",
  "expires_in": 900,
  "refresh_expires_in": 604800,
  "user": {
    "id": "user-123",
    "email": "dev@example.com",
    "role": "user"
  }
}

GET

/auth/verify

Verify current token is valid

Requires authentication

Response:

{
  "valid": true,
  "user_id": "user-123",
  "expires_at": "2025-10-10T10:30:00Z"
}

POST

/auth/logout

Invalidate current session

Requires authentication

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

Backup Endpoints

POST

/backups

Create a new backup (upload file)

Requires authentication

Request Body:

multipart/form-data with 'file' field

Response:

{
  "backup_id": "backup-12345-abcdef",
  "filename": "document.pdf",
  "size_bytes": 1048576,
  "chunks": 1,
  "shards": 10,
  "regions": [
    "us-east-1",
    "us-west-2",
    "eu-west-1"
  ],
  "status": "completed",
  "created_at": "2025-10-10T09:15:00Z",
  "encryption_key": "base64_encrypted_key_here",
  "retention_until": "2032-10-10T09:15:00Z",
  "upload_proof_generated": true,
  "upload_proof_id": "proof-upload-789"
}

GET

/backups

List all backups for current user

Requires authentication

Response:

[
  {
    "backup_id": "backup-12345",
    "filename": "document.pdf",
    "size_bytes": 1048576,
    "chunks": 1,
    "shards": 10,
    "regions": [
      "us-east-1",
      "eu-west-1"
    ],
    "status": "completed",
    "created_at": "2025-10-10T09:15:00Z",
    "retention_until": "2032-10-10T09:15:00Z",
    "legal_hold": false
  }
]

GET

/backups/{backup_id}

Get detailed backup information

Requires authentication

Response:

{
  "backup_id": "backup-12345",
  "filename": "document.pdf",
  "size_bytes": 1048576,
  "chunks": 1,
  "shards": 10,
  "regions": [
    "us-east-1",
    "us-west-2",
    "eu-west-1"
  ],
  "status": "completed",
  "created_at": "2025-10-10T09:15:00Z",
  "retention_until": "2032-10-10T09:15:00Z",
  "user_tags": [
    "legal",
    "confidential"
  ],
  "system_tags": [
    "encrypted",
    "distributed"
  ],
  "compliance_frameworks": [
    "GDPR",
    "HIPAA"
  ],
  "data_classification": "confidential",
  "upload_proof_generated": true,
  "residency_proof_generated": true
}

GET

/backups/{backup_id}/data

Download backup file (restore)

Requires authentication

Response:

Binary file stream (application/octet-stream)

DELETE

/backups/{backup_id}

Delete backup with cryptographic proof (GDPR Article 17)

Requires authentication

Response:

{
  "backup_id": "backup-12345",
  "deleted_at": "2025-10-10T10:30:00Z",
  "shard_count": 10,
  "verified": true,
  "deletion_signature": "SHA256:abcd1234...",
  "shard_proofs": [
    {
      "shard_id": "shard-001",
      "node_id": "node-us-east-1",
      "signature": "sig_abc123",
      "deleted_at": "2025-10-10T10:30:01Z",
      "verification_method": "signature",
      "verified": true
    }
  ]
}

Dashboard Endpoints

GET

/api/dashboard/summary

Get dashboard overview statistics

Requires authentication

Response:

{
  "total_backups": 42,
  "total_size_bytes": 104857600,
  "storage_used_gb": 100,
  "storage_limit_gb": 5000,
  "recent_backups": [],
  "active_vaults": 3,
  "deletion_proofs_generated": 5
}

GET

/api/vaults

List all vaults for organization

Requires authentication

Response:

[
  {
    "vault_id": "vault-123",
    "name": "Legal Documents",
    "backup_count": 15,
    "total_size_bytes": 52428800,
    "created_at": "2025-01-01T00:00:00Z"
  }
]

Account Endpoints

GET

/account/usage

Get current usage statistics

Requires authentication

Response:

{
  "storage_used_bytes": 104857600,
  "storage_limit_bytes": 5368709120,
  "api_calls_this_month": 1250,
  "api_calls_limit": 10000,
  "backups_count": 42
}

Audit Log Endpoints

GET

/audit/events

List audit events with pagination and filtering

Requires authentication

Query Parameters:

limit(integer)- Number of events to return (default: 100)

offset(integer)- Pagination offset (default: 0)

user_id(string)- Filter by user ID

action(string)- Filter by action type

outcome(string)- Filter by outcome (success/failure)

Response:

{
  "events": [
    {
      "event_id": "evt-001",
      "timestamp": "2025-10-10T09:15:00Z",
      "user_id": "user-123",
      "user_email": "user@example.com",
      "action": "backup_created",
      "resource_type": "backup",
      "resource_id": "backup-456",
      "outcome": "success",
      "ip_address": "192.168.1.1",
      "size_bytes": 1048576,
      "compliance_frameworks": [
        "GDPR"
      ],
      "zero_knowledge": true
    }
  ],
  "total": 1250,
  "limit": 100,
  "offset": 0
}

GET

/audit/stats

Get audit log statistics

Requires authentication

Response:

{
  "total_events": 1250,
  "earliest_event": "2025-01-01T00:00:00Z",
  "latest_event": "2025-10-10T10:30:00Z",
  "by_action": {
    "backup_created": 42,
    "backup_deleted": 5,
    "user_login": 103
  },
  "by_outcome": {
    "success": 1200,
    "failure": 50
  },
  "integrity_verified": true,
  "integrity_error": null
}

Retention Management Endpoints

GET

/retention/policies

List retention policies

Requires authentication

Response:

[
  {
    "policy_id": "pol-001",
    "name": "HIPAA 6-year retention",
    "description": "Healthcare records retention per HIPAA",
    "compliance_framework": "HIPAA",
    "retention_days": 2190,
    "alert_at_days": [
      30,
      7,
      1
    ],
    "auto_delete_enabled": false,
    "auto_delete_requires_approval": true,
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
]

GET

/retention/summary

Get retention summary and cost savings

Requires authentication

Response:

{
  "total_backups": 42,
  "backups_with_retention": 38,
  "backups_eligible_for_deletion": 4,
  "backups_approaching_retention": 6,
  "total_storage_bytes": 104857600,
  "potential_savings_monthly": 12.5,
  "potential_savings_annual": 150,
  "legal_holds_active": 0,
  "pending_alerts": 2
}

POST

/retention/legal-hold

Place legal hold on backup (prevents deletion)

Requires authentication

Request Body:

{
  "backup_id": "backup-12345",
  "reason": "Litigation hold - Case #2025-001"
}

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "legal_hold": true,
  "message": "Legal hold applied"
}

DELETE

/retention/legal-hold/{backup_id}

Remove legal hold from backup

Requires authentication

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "legal_hold": false,
  "message": "Legal hold removed"
}

POST

/retention/extend

Extend retention period for backup

Requires authentication

Request Body:

{
  "backup_id": "backup-12345",
  "new_retention_until": "2035-01-01T00:00:00Z",
  "reason": "Extended for regulatory compliance"
}

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "old_retention_until": "2032-10-10T09:15:00Z",
  "new_retention_until": "2035-01-01T00:00:00Z",
  "message": "Retention extended"
}

Compliance Endpoints

GET

/compliance/report

Generate compliance report for auditors

Requires authentication

Query Parameters:

framework(string)- GDPR, HIPAA, SOC2, etc.

start_date(string)- ISO 8601 date

end_date(string)- ISO 8601 date

Response:

{
  "framework": "GDPR",
  "report_period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-10-10T23:59:59Z"
  },
  "total_backups": 42,
  "deletion_requests": 5,
  "deletion_proofs_generated": 5,
  "residency_violations": 0,
  "audit_events": 1250,
  "compliance_score": 100
}

GET

/compliance/deletion-proofs

List all GDPR deletion proofs

Requires authentication

Response:

[
  {
    "backup_id": "backup-12345",
    "deleted_at": "2025-10-05T02:55:06Z",
    "shard_count": 10,
    "verified": true,
    "deletion_signature": "SHA256:2f51b5deaea...",
    "certificate_url": "/proofs/deletion/backup-12345.pdf"
  }
]

Admin Endpoints

Admin Only

These endpoints require admin or super_admin role

GET

/admin/roles

List all available roles and permissions

Requires authentication

Response:

[
  {
    "role": "user",
    "description": "Standard user with backup permissions",
    "permissions": [
      "backup:create",
      "backup:read",
      "backup:delete"
    ]
  },
  {
    "role": "admin",
    "description": "Admin with elevated permissions",
    "permissions": [
      "*"
    ]
  }
]

GET

/admin/users/{user_id}

Get user details (admin only)

Requires authentication

Response:

{
  "id": "user-123",
  "email": "user@example.com",
  "role": "user",
  "tier": "professional",
  "created_at": "2025-01-01T00:00:00Z",
  "backup_count": 42,
  "storage_used_bytes": 104857600
}

POST

/admin/users/{user_id}/role

Update user role (admin only)

Requires authentication

Request Body:

{
  "role": "admin"
}

Response:

{
  "success": true,
  "user_id": "user-123",
  "old_role": "user",
  "new_role": "admin"
}

Monitoring Endpoints

GET

/health

Health check endpoint for monitoring

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400,
  "database": "connected",
  "storage": "available"
}

GET

/monitoring/metrics

Get system metrics

Requires authentication

Response:

{
  "api_calls_total": 125000,
  "api_calls_per_minute": 42,
  "backups_total": 1250,
  "storage_used_bytes": 1073741824,
  "active_users": 15,
  "uptime_seconds": 86400
}

BYOC Provisioning Endpoints

POST

/api/v1/provisioning/deploy

Provision BYOC storage infrastructure

Requires authentication

Request Body:

{
  "provider": "azure",
  "region": "eastus",
  "method": "quick_launch",
  "credentials": {
    "subscription_id": "your-subscription-id",
    "tenant_id": "your-tenant-id",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }
}

Response:

{
  "success": true,
  "provider": "azure",
  "region": "eastus",
  "deployment_id": "deploy-789",
  "account_name": "nebulaguard123",
  "endpoint": "https://nebulaguard123.blob.core.windows.net",
  "status": "provisioned",
  "message": "Storage account created successfully"
}

SDK Examples

Python SDK

from nebula import NebulaClient

# Initialize client
client = NebulaClient(
    endpoint="https://api.nebula.guard",
    api_key="your-api-key-here"
)

# Create backup
backup = client.backup(
    path="/path/to/file.pdf",
    retention_years=7,
    tags=["legal", "confidential"]
)
print(f"Backup ID: {backup.backup_id}")

# List backups
backups = client.list_backups()
for backup in backups:
    print(f"{backup.filename} - {backup.status}")

# Restore backup
client.restore(
    backup_id="backup-12345",
    destination="/restore/path"
)

# Delete with proof
proof = client.delete_with_proof(
    backup_id="backup-12345",
    reason="GDPR Article 17 request"
)
print(f"Deletion verified: {proof.verified}")

cURL Examples

# Login
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"password"}'

# Upload backup
curl -X POST http://localhost:8000/backups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.pdf"

# List backups
curl -X GET http://localhost:8000/backups \
  -H "Authorization: Bearer YOUR_TOKEN"

# Download backup
curl -X GET http://localhost:8000/backups/backup-12345/data \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o restored-file.pdf

# Delete with proof
curl -X DELETE http://localhost:8000/backups/backup-12345 \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

Bearer Token Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN_HERE

Token Security

Access tokens expire after 15 minutes. Use the refresh token endpoint to get a new access token.

Getting Your API Token

1.Log in to your account via /auth/login
2.Copy the access_token from the response
3.Include it in the Authorization header of all subsequent requests

Rate Limits

100

req/min

Starter

1,000

req/min

Professional

Custom

Contact sales

Enterprise

Rate limit headers are included in all responses:

• X-RateLimit-Limit - Total requests allowed per window
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when the limit resets

Error Codes

Code	Meaning
200	OK - Request successful
201	Created - Resource created successfully
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Authentication Endpoints

POST

/auth/login

Authenticate user and receive access token

Request Body:

{
  "email": "dev@example.com",
  "password": "password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_abc123xyz...",
  "token_type": "bearer",
  "expires_in": 900,
  "refresh_expires_in": 604800,
  "user": {
    "id": "user-123",
    "email": "dev@example.com",
    "role": "user",
    "tier": "professional"
  }
}

POST

/api/v1/auth/signup

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123!@#",
  "company_name": "Acme Corp",
  "tier": "trial"
}

Response:

{
  "success": true,
  "user_id": "user-456",
  "email": "user@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "organization_id": "org-789",
  "tier": "trial",
  "role": "user"
}

POST

/auth/refresh

Refresh access token using refresh token

Request Body:

{
  "refresh_token": "refresh_abc123xyz..."
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_def456uvw...",
  "token_type": "bearer",
  "expires_in": 900,
  "refresh_expires_in": 604800,
  "user": {
    "id": "user-123",
    "email": "dev@example.com",
    "role": "user"
  }
}

GET

/auth/verify

Verify current token is valid

Requires authentication

Response:

{
  "valid": true,
  "user_id": "user-123",
  "expires_at": "2025-10-10T10:30:00Z"
}

POST

/auth/logout

Invalidate current session

Requires authentication

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

Backup Endpoints

POST

/backups

Create a new backup (upload file)

Requires authentication

Request Body:

multipart/form-data with 'file' field

Response:

{
  "backup_id": "backup-12345-abcdef",
  "filename": "document.pdf",
  "size_bytes": 1048576,
  "chunks": 1,
  "shards": 10,
  "regions": [
    "us-east-1",
    "us-west-2",
    "eu-west-1"
  ],
  "status": "completed",
  "created_at": "2025-10-10T09:15:00Z",
  "encryption_key": "base64_encrypted_key_here",
  "retention_until": "2032-10-10T09:15:00Z",
  "upload_proof_generated": true,
  "upload_proof_id": "proof-upload-789"
}

GET

/backups

List all backups for current user

Requires authentication

Response:

[
  {
    "backup_id": "backup-12345",
    "filename": "document.pdf",
    "size_bytes": 1048576,
    "chunks": 1,
    "shards": 10,
    "regions": [
      "us-east-1",
      "eu-west-1"
    ],
    "status": "completed",
    "created_at": "2025-10-10T09:15:00Z",
    "retention_until": "2032-10-10T09:15:00Z",
    "legal_hold": false
  }
]

GET

/backups/{backup_id}

Get detailed backup information

Requires authentication

Response:

{
  "backup_id": "backup-12345",
  "filename": "document.pdf",
  "size_bytes": 1048576,
  "chunks": 1,
  "shards": 10,
  "regions": [
    "us-east-1",
    "us-west-2",
    "eu-west-1"
  ],
  "status": "completed",
  "created_at": "2025-10-10T09:15:00Z",
  "retention_until": "2032-10-10T09:15:00Z",
  "user_tags": [
    "legal",
    "confidential"
  ],
  "system_tags": [
    "encrypted",
    "distributed"
  ],
  "compliance_frameworks": [
    "GDPR",
    "HIPAA"
  ],
  "data_classification": "confidential",
  "upload_proof_generated": true,
  "residency_proof_generated": true
}

GET

/backups/{backup_id}/data

Download backup file (restore)

Requires authentication

Response:

Binary file stream (application/octet-stream)

DELETE

/backups/{backup_id}

Delete backup with cryptographic proof (GDPR Article 17)

Requires authentication

Response:

{
  "backup_id": "backup-12345",
  "deleted_at": "2025-10-10T10:30:00Z",
  "shard_count": 10,
  "verified": true,
  "deletion_signature": "SHA256:abcd1234...",
  "shard_proofs": [
    {
      "shard_id": "shard-001",
      "node_id": "node-us-east-1",
      "signature": "sig_abc123",
      "deleted_at": "2025-10-10T10:30:01Z",
      "verification_method": "signature",
      "verified": true
    }
  ]
}

Dashboard Endpoints

GET

/api/dashboard/summary

Get dashboard overview statistics

Requires authentication

Response:

{
  "total_backups": 42,
  "total_size_bytes": 104857600,
  "storage_used_gb": 100,
  "storage_limit_gb": 5000,
  "recent_backups": [],
  "active_vaults": 3,
  "deletion_proofs_generated": 5
}

GET

/api/vaults

List all vaults for organization

Requires authentication

Response:

[
  {
    "vault_id": "vault-123",
    "name": "Legal Documents",
    "backup_count": 15,
    "total_size_bytes": 52428800,
    "created_at": "2025-01-01T00:00:00Z"
  }
]

Account Endpoints

GET

/account/usage

Get current usage statistics

Requires authentication

Response:

{
  "storage_used_bytes": 104857600,
  "storage_limit_bytes": 5368709120,
  "api_calls_this_month": 1250,
  "api_calls_limit": 10000,
  "backups_count": 42
}

Audit Log Endpoints

GET

/audit/events

List audit events with pagination and filtering

Requires authentication

Query Parameters:

limit(integer)- Number of events to return (default: 100)

offset(integer)- Pagination offset (default: 0)

user_id(string)- Filter by user ID

action(string)- Filter by action type

outcome(string)- Filter by outcome (success/failure)

Response:

{
  "events": [
    {
      "event_id": "evt-001",
      "timestamp": "2025-10-10T09:15:00Z",
      "user_id": "user-123",
      "user_email": "user@example.com",
      "action": "backup_created",
      "resource_type": "backup",
      "resource_id": "backup-456",
      "outcome": "success",
      "ip_address": "192.168.1.1",
      "size_bytes": 1048576,
      "compliance_frameworks": [
        "GDPR"
      ],
      "zero_knowledge": true
    }
  ],
  "total": 1250,
  "limit": 100,
  "offset": 0
}

GET

/audit/stats

Get audit log statistics

Requires authentication

Response:

{
  "total_events": 1250,
  "earliest_event": "2025-01-01T00:00:00Z",
  "latest_event": "2025-10-10T10:30:00Z",
  "by_action": {
    "backup_created": 42,
    "backup_deleted": 5,
    "user_login": 103
  },
  "by_outcome": {
    "success": 1200,
    "failure": 50
  },
  "integrity_verified": true,
  "integrity_error": null
}

Retention Management Endpoints

GET

/retention/policies

List retention policies

Requires authentication

Response:

[
  {
    "policy_id": "pol-001",
    "name": "HIPAA 6-year retention",
    "description": "Healthcare records retention per HIPAA",
    "compliance_framework": "HIPAA",
    "retention_days": 2190,
    "alert_at_days": [
      30,
      7,
      1
    ],
    "auto_delete_enabled": false,
    "auto_delete_requires_approval": true,
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
]

GET

/retention/summary

Get retention summary and cost savings

Requires authentication

Response:

{
  "total_backups": 42,
  "backups_with_retention": 38,
  "backups_eligible_for_deletion": 4,
  "backups_approaching_retention": 6,
  "total_storage_bytes": 104857600,
  "potential_savings_monthly": 12.5,
  "potential_savings_annual": 150,
  "legal_holds_active": 0,
  "pending_alerts": 2
}

POST

/retention/legal-hold

Place legal hold on backup (prevents deletion)

Requires authentication

Request Body:

{
  "backup_id": "backup-12345",
  "reason": "Litigation hold - Case #2025-001"
}

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "legal_hold": true,
  "message": "Legal hold applied"
}

DELETE

/retention/legal-hold/{backup_id}

Remove legal hold from backup

Requires authentication

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "legal_hold": false,
  "message": "Legal hold removed"
}

POST

/retention/extend

Extend retention period for backup

Requires authentication

Request Body:

{
  "backup_id": "backup-12345",
  "new_retention_until": "2035-01-01T00:00:00Z",
  "reason": "Extended for regulatory compliance"
}

Response:

{
  "success": true,
  "backup_id": "backup-12345",
  "old_retention_until": "2032-10-10T09:15:00Z",
  "new_retention_until": "2035-01-01T00:00:00Z",
  "message": "Retention extended"
}

Compliance Endpoints

GET

/compliance/report

Generate compliance report for auditors

Requires authentication

Query Parameters:

framework(string)- GDPR, HIPAA, SOC2, etc.

start_date(string)- ISO 8601 date

end_date(string)- ISO 8601 date

Response:

{
  "framework": "GDPR",
  "report_period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-10-10T23:59:59Z"
  },
  "total_backups": 42,
  "deletion_requests": 5,
  "deletion_proofs_generated": 5,
  "residency_violations": 0,
  "audit_events": 1250,
  "compliance_score": 100
}

GET

/compliance/deletion-proofs

List all GDPR deletion proofs

Requires authentication

Response:

[
  {
    "backup_id": "backup-12345",
    "deleted_at": "2025-10-05T02:55:06Z",
    "shard_count": 10,
    "verified": true,
    "deletion_signature": "SHA256:2f51b5deaea...",
    "certificate_url": "/proofs/deletion/backup-12345.pdf"
  }
]

Admin Endpoints

Admin Only

These endpoints require admin or super_admin role

GET

/admin/roles

List all available roles and permissions

Requires authentication

Response:

[
  {
    "role": "user",
    "description": "Standard user with backup permissions",
    "permissions": [
      "backup:create",
      "backup:read",
      "backup:delete"
    ]
  },
  {
    "role": "admin",
    "description": "Admin with elevated permissions",
    "permissions": [
      "*"
    ]
  }
]

GET

/admin/users/{user_id}

Get user details (admin only)

Requires authentication

Response:

{
  "id": "user-123",
  "email": "user@example.com",
  "role": "user",
  "tier": "professional",
  "created_at": "2025-01-01T00:00:00Z",
  "backup_count": 42,
  "storage_used_bytes": 104857600
}

POST

/admin/users/{user_id}/role

Update user role (admin only)

Requires authentication

Request Body:

{
  "role": "admin"
}

Response:

{
  "success": true,
  "user_id": "user-123",
  "old_role": "user",
  "new_role": "admin"
}

Monitoring Endpoints

GET

/health

Health check endpoint for monitoring

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400,
  "database": "connected",
  "storage": "available"
}

GET

/monitoring/metrics

Get system metrics

Requires authentication

Response:

{
  "api_calls_total": 125000,
  "api_calls_per_minute": 42,
  "backups_total": 1250,
  "storage_used_bytes": 1073741824,
  "active_users": 15,
  "uptime_seconds": 86400
}

BYOC Provisioning Endpoints

POST

/api/v1/provisioning/deploy

Provision BYOC storage infrastructure

Requires authentication

Request Body:

{
  "provider": "azure",
  "region": "eastus",
  "method": "quick_launch",
  "credentials": {
    "subscription_id": "your-subscription-id",
    "tenant_id": "your-tenant-id",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }
}

Response:

{
  "success": true,
  "provider": "azure",
  "region": "eastus",
  "deployment_id": "deploy-789",
  "account_name": "nebulaguard123",
  "endpoint": "https://nebulaguard123.blob.core.windows.net",
  "status": "provisioned",
  "message": "Storage account created successfully"
}

SDK Examples

Python SDK

from nebula import NebulaClient

# Initialize client
client = NebulaClient(
    endpoint="https://api.nebula.guard",
    api_key="your-api-key-here"
)

# Create backup
backup = client.backup(
    path="/path/to/file.pdf",
    retention_years=7,
    tags=["legal", "confidential"]
)
print(f"Backup ID: {backup.backup_id}")

# List backups
backups = client.list_backups()
for backup in backups:
    print(f"{backup.filename} - {backup.status}")

# Restore backup
client.restore(
    backup_id="backup-12345",
    destination="/restore/path"
)

# Delete with proof
proof = client.delete_with_proof(
    backup_id="backup-12345",
    reason="GDPR Article 17 request"
)
print(f"Deletion verified: {proof.verified}")

cURL Examples

# Login
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"password"}'

# Upload backup
curl -X POST http://localhost:8000/backups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.pdf"

# List backups
curl -X GET http://localhost:8000/backups \
  -H "Authorization: Bearer YOUR_TOKEN"

# Download backup
curl -X GET http://localhost:8000/backups/backup-12345/data \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o restored-file.pdf

# Delete with proof
curl -X DELETE http://localhost:8000/backups/backup-12345 \
  -H "Authorization: Bearer YOUR_TOKEN"

API Reference

Authentication

Bearer Token Authentication

Getting Your API Token

Rate Limits

Error Codes

Authentication Endpoints

Backup Endpoints

Dashboard Endpoints

Account Endpoints

Audit Log Endpoints

Retention Management Endpoints

Compliance Endpoints

Admin Endpoints

Monitoring Endpoints

BYOC Provisioning Endpoints

SDK Examples

Python SDK

cURL Examples

API Reference

Authentication

Bearer Token Authentication

Getting Your API Token

Rate Limits

Error Codes

Authentication Endpoints

Backup Endpoints

Dashboard Endpoints

Account Endpoints

Audit Log Endpoints

Retention Management Endpoints

Compliance Endpoints

Admin Endpoints

Monitoring Endpoints

BYOC Provisioning Endpoints

SDK Examples

Python SDK

cURL Examples