API Overview

The LOX API is a RESTful API that allows you to programmatically manage backups, storage, and tenant settings.

v1.0.0Updated 2026-01-10

Base URL

https://backlox.com/api

Version

v1

Auth

Bearer Token

Authentication

All API requests require authentication using your API key in the Authorization header:

curl https://backlox.com/api/v1/backups \
  -H "Authorization: Bearer lox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

API Key Security

Your API key carries full access to your account. Keep it secret, use environment variables, and never commit it to version control.

Request Format

All requests should use JSON for request bodies and accept JSON responses:

curl -X POST https://backlox.com/api/v1/backups \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "daily-backup",
    "size_bytes": 1048576
  }'

API Endpoints

Backups

Method	Endpoint	Description
GET	/v1/backups	List all backups
POST	/v1/backups	Create new backup (get upload URL)
GET	/v1/backups/:id	Get backup details
POST	/v1/backups/:id/complete	Mark upload as complete
GET	/v1/backups/:id/download	Get download URL
DELETE	/v1/backups/:id	Delete a backup

Tenant / Account

Method	Endpoint	Description
GET	/v1/tenant	Get tenant info
PATCH	/v1/tenant	Update tenant settings
GET	/v1/tenant/api-keys	List API keys
POST	/v1/tenant/api-keys	Create new API key
DELETE	/v1/tenant/api-keys/:id	Revoke API key

Storage

Method	Endpoint	Description
GET	/v1/storage	Get storage usage and quota
GET	/v1/storage/stats	Get detailed storage statistics

Common Operations

Create a Backup

Creating a backup is a two-step process: request an upload URL, then upload the file.

# Step 1: Request upload URL
curl -X POST https://backlox.com/api/v1/backups \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-backup-2024-01-15",
    "size_bytes": 52428800,
    "content_type": "application/gzip",
    "metadata": {
      "source": "production-server",
      "database": "myapp"
    }
  }'

# Response:
{
  "id": "bkp_abc123def456",
  "name": "daily-backup-2024-01-15",
  "status": "pending",
  "upload_url": "https://storage.backlox.com/upload/...",
  "upload_expires_at": "2024-01-15T11:00:00Z"
}

# Step 2: Upload the file to the upload URL
curl -X PUT "https://storage.backlox.com/upload/..." \
  -H "Content-Type: application/gzip" \
  --data-binary @backup.tar.gz

# Step 3: Mark upload as complete
curl -X POST https://backlox.com/api/v1/backups/bkp_abc123def456/complete \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Response:
{
  "id": "bkp_abc123def456",
  "name": "daily-backup-2024-01-15",
  "status": "completed",
  "size_bytes": 52428800,
  "checksum": "sha256:a1b2c3d4e5f6...",
  "created_at": "2024-01-15T10:30:00Z"
}

List Backups

# List all backups with pagination
curl "https://backlox.com/api/v1/backups?limit=10&offset=0" \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Filter by status
curl "https://backlox.com/api/v1/backups?status=completed" \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Filter by date range
curl "https://backlox.com/api/v1/backups?created_after=2024-01-01&created_before=2024-01-31" \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Response:
{
  "backups": [
    {
      "id": "bkp_abc123",
      "name": "daily-backup-2024-01-15",
      "status": "completed",
      "size_bytes": 52428800,
      "created_at": "2024-01-15T10:30:00Z"
    },
    // ...more backups
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Download a Backup

# Get download URL
curl https://backlox.com/api/v1/backups/bkp_abc123/download \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Response:
{
  "download_url": "https://storage.backlox.com/download/...",
  "expires_at": "2024-01-15T11:30:00Z",
  "size_bytes": 52428800,
  "checksum": "sha256:a1b2c3d4e5f6..."
}

# Download the file
curl -o backup.tar.gz "https://storage.backlox.com/download/..."

Get Storage Info

curl https://backlox.com/api/v1/storage \
  -H "Authorization: Bearer lox_xxxxxxxxxxxx"

# Response:
{
  "used_bytes": 1073741824,
  "quota_bytes": 5368709120,
  "used_percentage": 20.0,
  "backup_count": 15,
  "oldest_backup": "2024-01-01T00:00:00Z",
  "newest_backup": "2024-01-15T10:30:00Z"
}

Pagination

List endpoints support pagination using limit and offset:

Parameter	Default	Description
limit	20	Number of items per page (max 100)
offset	0	Number of items to skip

Error Handling

The API uses standard HTTP status codes and returns error details in JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "name": "Name is required",
      "size_bytes": "Must be a positive integer"
    }
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created successfully
400	Bad request - invalid parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - insufficient permissions
404	Not found - resource doesn't exist
429	Rate limited - too many requests
500	Server error - try again later

Error Codes

Code	Description
validation_error	Request body validation failed
authentication_error	Invalid or expired API key
quota_exceeded	Storage quota limit reached
rate_limited	Too many requests, retry after delay
upload_expired	Upload URL has expired
backup_not_found	Backup with given ID not found

Rate Limiting

The API implements dual-cap rate limiting to ensure fair usage and prevent abuse. Limits are enforced both per-minute (prevents burst attacks) and per-hour (prevents sustained abuse). When you exceed either limit, you'll receive a 429 Too Many Requests response.

Limits by Plan

Rate limits vary by subscription tier and endpoint type. Format: per minute / per hour

Plan	API Calls	Uploads	Downloads
Free	10 / 60	2 / 5	3 / 20
Solo	30 / 300	5 / 50	10 / 100
Pro	100 / 1,000	20 / 200	40 / 400
Business	300 / 2,500	50 / 500	100 / 1,000
Enterprise	1,000 / 8,000	150 / 1,500	300 / 3,000

Rate Limit Headers

All responses include headers for both per-minute and per-hour limits:

# Per-minute headers (standard)
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 45

# Per-hour headers (extended)
X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 892
X-RateLimit-Reset-Hour: 2847

# Only on 429 responses
Retry-After: 30

Dual-Cap Enforcement

Both limits must pass for a request to succeed. Even if you have minute quota remaining, exceeding the hourly limit will result in a 429 response. This prevents "drip attacks" that stay under the minute limit but abuse the API over time.

Webhooks

Configure webhooks to receive notifications when backups complete or fail:

# Webhook payload for backup.completed event
{
  "event": "backup.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "bkp_abc123",
    "name": "daily-backup",
    "status": "completed",
    "size_bytes": 52428800,
    "checksum": "sha256:a1b2c3d4..."
  }
}

# Webhook payload for backup.failed event
{
  "event": "backup.failed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "bkp_abc123",
    "name": "daily-backup",
    "status": "failed",
    "error": "Upload timeout exceeded"
  }
}

Webhook Verification

All webhook requests include a X-LOX-Signature header with an HMAC-SHA256 signature. Verify this signature using your webhook secret.

SDKs & Tools

Use our official SDKs for easier integration: