Backups API

The Backups API provides endpoints for creating, managing, and restoring backups. You can execute manual backups, list backup history, verify integrity, preview contents, and restore data.

Endpoints Overview

Method	Endpoint	Description
POST	/backups	Execute a backup
GET	/backups/project/:projectId	List backups for a project
GET	/backups/:projectId/:backupId	Get backup details
POST	/backups/restore	Restore from backup
GET	/backups/:projectId/:backupId/verify	Verify backup integrity
GET	/backups/:projectId/:backupId/preview	Preview backup contents
GET	/backups/:projectId/diff	Compare two backups
DELETE	/backups/:projectId/:backupId	Delete a backup

Execute Backup

Create a new backup for a project.

POST /api/v1/backups
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "projectId": "proj_abc123",
  "type": "full",
  "collections": ["users", "orders"],
  "includeSubcollections": true,
  "includeAuth": false,
  "storageDestinationId": "storage_xyz789",
  "compression": "brotli",
  "encrypt": true
}

Request Body:

Field	Type	Required	Default	Description
projectId	string	Yes	-	Project to backup
type	string	No	full	full or incremental
collections	array	No	All	Collections to backup
includeSubcollections	boolean	No	true	Include subcollections
includeAuth	boolean	No	false	Include Firebase Auth users
storageDestinationId	string	No	Default	Storage destination
compression	string	No	brotli	brotli, gzip, or none
encrypt	boolean	No	true	Enable encryption

Response:

{
  "success": true,
  "data": {
    "id": "bkp_xyz789",
    "projectId": "proj_abc123",
    "type": "full",
    "status": "pending",
    "collections": ["users", "orders"],
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Backup Status Flow

pending → running → compressing → encrypting → uploading → completed
                                                        └→ failed

List Backups

Get all backups for a project.

GET /api/v1/backups/project/:projectId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
status	string	-	Filter: completed, failed, pending, running
type	string	-	Filter: full, incremental, pitr
from	string	-	ISO 8601 start date
to	string	-	ISO 8601 end date

Response:

{
  "success": true,
  "data": [
    {
      "id": "bkp_xyz789",
      "projectId": "proj_abc123",
      "type": "full",
      "status": "completed",
      "documentsCount": 15000,
      "collectionsCount": 12,
      "originalSize": 45000000,
      "compressedSize": 6200000,
      "duration": 45,
      "createdAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:00:45Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Get Backup Details

Retrieve detailed information about a specific backup.

GET /api/v1/backups/:projectId/:backupId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "bkp_xyz789",
    "projectId": "proj_abc123",
    "type": "full",
    "status": "completed",
    "collections": [
      { "name": "users", "documentsCount": 10000, "size": 30000000 },
      { "name": "orders", "documentsCount": 5000, "size": 15000000 }
    ],
    "includeSubcollections": true,
    "includeAuth": false,
    "documentsCount": 15000,
    "collectionsCount": 2,
    "originalSize": 45000000,
    "compressedSize": 6200000,
    "compressionRatio": 0.86,
    "compression": "brotli",
    "encrypted": true,
    "checksum": "sha256:a1b2c3d4e5f6...",
    "storageDestination": {
      "id": "storage_xyz789",
      "type": "s3",
      "bucket": "my-backup-bucket",
      "path": "backups/proj_abc123/bkp_xyz789.fbk"
    },
    "duration": 45,
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:00:45Z",
    "createdBy": {
      "id": "user_abc123",
      "email": "user@example.com"
    }
  }
}

Restore from Backup

Restore data from a backup to a project.

POST /api/v1/backups/restore
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "backupId": "bkp_xyz789",
  "projectId": "proj_abc123",
  "targetProjectId": "proj_def456",
  "collections": ["users"],
  "mergeMode": "overwrite",
  "dryRun": false
}

Request Body:

Field	Type	Required	Default	Description
backupId	string	Yes	-	Backup to restore from
projectId	string	Yes	-	Source project ID
targetProjectId	string	No	Same	Target project (cross-project restore)
collections	array	No	All	Collections to restore
mergeMode	string	No	overwrite	overwrite, skip_existing, merge
dryRun	boolean	No	false	Preview without writing

Response:

{
  "success": true,
  "data": {
    "restoreJobId": "restore_abc123",
    "status": "pending",
    "backupId": "bkp_xyz789",
    "targetProjectId": "proj_def456",
    "collections": ["users"],
    "mergeMode": "overwrite",
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

Get Restore Status

GET /api/v1/backups/restore/:restoreJobId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "restore_abc123",
    "status": "completed",
    "progress": 100,
    "documentsRestored": 10000,
    "collectionsRestored": 1,
    "errors": [],
    "startedAt": "2024-01-15T11:00:00Z",
    "completedAt": "2024-01-15T11:02:30Z"
  }
}

Verify Backup Integrity

Verify that a backup is valid and can be restored.

GET /api/v1/backups/:projectId/:backupId/verify
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "checks": {
      "fileExists": true,
      "checksumValid": true,
      "decryptable": true,
      "decompressable": true,
      "structureValid": true
    },
    "verifiedAt": "2024-01-15T11:00:00Z"
  }
}

Verification Failure

{
  "success": true,
  "data": {
    "valid": false,
    "checks": {
      "fileExists": true,
      "checksumValid": false,
      "decryptable": null,
      "decompressable": null,
      "structureValid": null
    },
    "error": "Checksum mismatch: expected sha256:abc123, got sha256:def456",
    "verifiedAt": "2024-01-15T11:00:00Z"
  }
}

Preview Backup Contents

Browse the contents of a backup without restoring.

GET /api/v1/backups/:projectId/:backupId/preview
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
collection	string	-	Specific collection to preview
limit	integer	10	Documents per collection (max 100)
path	string	-	Document path to preview

Response (Collection List):

{
  "success": true,
  "data": {
    "collections": [
      {
        "name": "users",
        "documentsCount": 10000,
        "sampleDocuments": [
          {
            "id": "user_1",
            "data": {
              "email": "user1@example.com",
              "name": "John Doe",
              "createdAt": "2024-01-01T00:00:00Z"
            }
          }
        ]
      }
    ]
  }
}

Response (Specific Document):

GET /api/v1/backups/:projectId/:backupId/preview?path=users/user_1

{
  "success": true,
  "data": {
    "path": "users/user_1",
    "document": {
      "id": "user_1",
      "data": {
        "email": "user1@example.com",
        "name": "John Doe",
        "createdAt": "2024-01-01T00:00:00Z"
      },
      "subcollections": ["settings", "notifications"]
    }
  }
}

Compare Backups (Diff)

Compare two backups to see differences.

GET /api/v1/backups/:projectId/diff
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Required	Description
backup1	string	Yes	First backup ID
backup2	string	Yes	Second backup ID
collection	string	No	Specific collection to compare

Response:

{
  "success": true,
  "data": {
    "backup1": {
      "id": "bkp_older",
      "createdAt": "2024-01-14T10:00:00Z"
    },
    "backup2": {
      "id": "bkp_newer",
      "createdAt": "2024-01-15T10:00:00Z"
    },
    "summary": {
      "added": 150,
      "modified": 45,
      "deleted": 10,
      "unchanged": 9795
    },
    "collections": {
      "users": {
        "added": 100,
        "modified": 25,
        "deleted": 5
      },
      "orders": {
        "added": 50,
        "modified": 20,
        "deleted": 5
      }
    },
    "changes": [
      {
        "type": "added",
        "collection": "users",
        "documentId": "user_new1"
      },
      {
        "type": "modified",
        "collection": "users",
        "documentId": "user_123",
        "fields": ["email", "updatedAt"]
      },
      {
        "type": "deleted",
        "collection": "users",
        "documentId": "user_old1"
      }
    ]
  }
}

Delete Backup

Permanently delete a backup from storage.

DELETE /api/v1/backups/:projectId/:backupId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Backup deleted successfully"
}

Permanent Deletion

Deleted backups cannot be recovered. Ensure you have alternative backups before deleting.

Backup Object

Field	Type	Description
id	string	Unique backup ID
projectId	string	Source project ID
type	string	full, incremental, or pitr
status	string	Current status
collections	array	Backed up collections with stats
documentsCount	integer	Total documents
collectionsCount	integer	Total collections
originalSize	integer	Size before compression (bytes)
compressedSize	integer	Size after compression (bytes)
compressionRatio	number	Compression ratio (0-1)
compression	string	Compression algorithm
encrypted	boolean	Whether backup is encrypted
checksum	string	SHA-256 checksum
storageDestination	object	Storage location details
duration	integer	Backup duration (seconds)
createdAt	string	ISO 8601 timestamp
completedAt	string	ISO 8601 timestamp
createdBy	object	User who initiated backup

Error Responses

Backup Not Found

{
  "success": false,
  "error": {
    "code": "BACKUP_NOT_FOUND",
    "message": "Backup 'bkp_xxx' not found"
  }
}

Backup In Progress

{
  "success": false,
  "error": {
    "code": "BACKUP_IN_PROGRESS",
    "message": "A backup is already in progress for this project"
  }
}

Restore Failed

{
  "success": false,
  "error": {
    "code": "RESTORE_FAILED",
    "message": "Failed to restore backup",
    "details": {
      "reason": "Insufficient permissions on target project",
      "documentsRestored": 5000,
      "failedAt": "users/user_5001"
    }
  }
}

Webhook Events

The following webhook events are triggered for backup operations:

Event	Description
backup.started	Backup job started
backup.progress	Backup progress update (25%, 50%, 75%)
backup.completed	Backup completed successfully
backup.failed	Backup failed
restore.started	Restore job started
restore.completed	Restore completed successfully
restore.failed	Restore failed

See Webhooks for event payload details.

Related

• Schedules API - Automate backups
• PITR API - Point-in-time recovery
• Storage API - Configure storage destinations
• Creating Backups - User guide