Storage API

The Storage API enables management of cloud storage destinations for backups. FireBackup supports multiple cloud providers including AWS S3, Google Cloud Storage, DigitalOcean Spaces, and Firebase Storage.

Endpoints Overview

Method	Endpoint	Description
POST	`/storage/connect`	Connect to storage provider
POST	`/storage/buckets/create`	Create a new bucket
POST	`/storage/buckets/verify`	Verify bucket access
POST	`/storage/buckets/folders`	List folders in bucket
POST	`/storage/buckets/folders/create`	Create folder in bucket
GET	`/storage/destinations`	List storage destinations
GET	`/storage/destinations/:id`	Get destination details
POST	`/storage/destinations`	Create storage destination
PUT	`/storage/destinations/:id`	Update storage destination
DELETE	`/storage/destinations/:id`	Delete storage destination
POST	`/storage/destinations/:id/verify`	Verify destination connection
GET	`/storage/destinations/:id/linked`	Get linked resources
GET	`/storage/destinations/:id/backups`	Get backups in destination
POST	`/storage/destinations/:id/backups/bulk-delete`	Bulk delete backups
POST	`/storage/destinations/:id/migrate`	Migrate resources to another storage
GET	`/storage/destinations/:id/files`	List files in storage
GET	`/storage/destinations/:id/files/stats`	Get storage statistics
DELETE	`/storage/destinations/:id/files`	Delete orphan file
POST	`/storage/destinations/:id/files/bulk-delete`	Bulk delete orphan files
POST	`/storage/destinations/:id/cleanup-orphans`	Delete all orphan files
GET	`/storage/stats`	Get organization storage stats
POST	`/storage/sync`	Trigger storage sync

Connect to Storage Provider

Connect to a cloud storage provider and list available buckets.

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

{
  "provider": "S3",
  "region": "us-east-1",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Supported Providers:

Provider	Type	Required Credentials
AWS S3	`S3`	`accessKeyId`, `secretAccessKey`
Google Cloud Storage	`gcs`	`keyFilename` or `projectId` + credentials
DigitalOcean Spaces	`do-spaces`	`accessKeyId`, `secretAccessKey`
Firebase Storage	`firebase-storage`	GCS credentials

Provider-Specific Examples:

AWS S3

{
  "provider": "S3",
  "region": "us-west-2",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Google Cloud Storage

{
  "provider": "gcs",
  "credentials": {
    "projectId": "my-project-id",
    "keyFilename": "/path/to/service-account.json"
  }
}

DigitalOcean Spaces

{
  "provider": "do-spaces",
  "region": "nyc3",
  "credentials": {
    "accessKeyId": "YOUR_ACCESS_KEY",
    "secretAccessKey": "YOUR_SECRET_KEY"
  }
}

Response:

{
  "success": true,
  "data": {
    "provider": "S3",
    "buckets": [
      {
        "name": "my-backup-bucket",
        "createdAt": "2024-01-01T00:00:00Z",
        "region": "us-east-1"
      },
      {
        "name": "production-backups",
        "createdAt": "2024-01-10T00:00:00Z",
        "region": "us-east-1"
      }
    ]
  },
  "message": "Connected to S3 and found 2 buckets"
}

Create Bucket

Create a new bucket in the storage provider.

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

{
  "provider": "S3",
  "bucketName": "my-firebase-backups",
  "region": "us-west-2",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Request Body:

Field	Type	Required	Description
`provider`	string	Yes	Storage provider type
`bucketName`	string	Yes	Name for the new bucket
`region`	string	No	Region for the bucket
`credentials`	object	Yes	Provider credentials

Response:

{
  "success": true,
  "data": {
    "bucket": "my-firebase-backups",
    "region": "us-west-2",
    "created": true
  },
  "message": "Bucket 'my-firebase-backups' created successfully"
}

Bucket Naming

S3: Bucket names must be globally unique across all AWS accounts
GCS: Requires storage.buckets.create permission
DO Spaces: Names must be unique within the region

Verify Bucket Access

Verify that credentials have proper access to a bucket.

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

{
  "provider": "S3",
  "bucketName": "my-existing-bucket",
  "region": "us-east-1",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Response:

{
  "success": true,
  "data": {
    "accessible": true,
    "permissions": {
      "read": true,
      "write": true,
      "delete": true
    },
    "bucket": "my-existing-bucket"
  }
}

List Folders

List all folders (prefixes) in a bucket.

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

{
  "provider": "S3",
  "bucketName": "my-backup-bucket",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Response:

{
  "success": true,
  "data": {
    "folders": [
      "backups/",
      "backups/production/",
      "backups/staging/",
      "archives/"
    ]
  }
}

Create Folder

Create a new folder in a bucket.

POST /api/v1/storage/buckets/folders/create
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "provider": "S3",
  "bucketName": "my-backup-bucket",
  "folderName": "backups/new-project",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Response:

{
  "success": true,
  "data": {
    "folder": "backups/new-project/",
    "created": true
  },
  "message": "Folder created successfully"
}

List Storage Destinations

Get all storage destinations for the organization.

GET /api/v1/storage/destinations
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": [
    {
      "id": "storage_abc123",
      "name": "Production S3",
      "type": "S3",
      "bucket": "my-backup-bucket",
      "path": "backups/production",
      "region": "us-east-1",
      "verified": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    },
    {
      "id": "storage_def456",
      "name": "Archive GCS",
      "type": "GCS",
      "bucket": "company-archives",
      "path": "firebase-backups",
      "region": "us-central1",
      "verified": true,
      "createdAt": "2024-01-10T00:00:00Z",
      "updatedAt": "2024-01-10T00:00:00Z"
    }
  ]
}

Get Storage Destination

Get details of a specific storage destination.

GET /api/v1/storage/destinations/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "storage_abc123",
    "name": "Production S3",
    "type": "S3",
    "bucket": "my-backup-bucket",
    "path": "backups/production",
    "region": "us-east-1",
    "verified": true,
    "credentials": {
      "accessKeyId": "AKIA...XXXX"
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Credential Security

Access keys and secrets are partially masked in API responses. Full credentials are never returned after initial creation.

Create Storage Destination

Save a storage destination for use with backups.

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

{
  "name": "Production S3 Bucket",
  "type": "S3",
  "bucket": "my-backup-bucket",
  "path": "backups/production",
  "region": "us-east-1",
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Display name
`type`	string	Yes	`S3`, `gcs`, `do-spaces`, `firebase-storage`
`bucket`	string	Yes	Bucket name
`path`	string	No	Base folder path for backups
`region`	string	No	Bucket region
`credentials`	object	Yes	Provider-specific credentials

Response:

{
  "success": true,
  "data": {
    "id": "storage_xyz789",
    "name": "Production S3 Bucket",
    "type": "S3",
    "bucket": "my-backup-bucket",
    "path": "backups/production",
    "region": "us-east-1",
    "verified": false,
    "createdAt": "2024-01-15T11:00:00Z"
  },
  "message": "Storage destination created successfully"
}

Update Storage Destination

Update storage destination settings.

PUT /api/v1/storage/destinations/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "name": "Production S3 (Primary)",
  "path": "backups/prod-v2"
}

Request Body:

Field	Type	Description
`name`	string	Display name
`bucket`	string	Bucket name
`path`	string	Base folder path
`region`	string	Bucket region
`credentials`	object	New credentials

Response:

{
  "success": true,
  "data": {
    "id": "storage_xyz789",
    "name": "Production S3 (Primary)",
    "path": "backups/prod-v2",
    "updatedAt": "2024-01-15T12:00:00Z"
  },
  "message": "Storage destination updated successfully"
}

Delete Storage Destination

Delete a storage destination.

DELETE /api/v1/storage/destinations/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Storage destination deleted successfully"
}

Linked Resources

Deleting a storage destination does not delete backups stored in it. Migrate linked schedules and PITR configurations before deleting.

Verify Storage Destination

Verify connectivity to a saved storage destination.

POST /api/v1/storage/destinations/:id/verify
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "verified": true,
    "accessible": true,
    "permissions": {
      "read": true,
      "write": true,
      "delete": true
    }
  },
  "message": "Storage verified successfully"
}

Get Linked Resources

Get all resources using this storage destination.

GET /api/v1/storage/destinations/:id/linked
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "schedules": [
      {
        "id": "sched_abc123",
        "name": "Daily Production Backup",
        "projectId": "proj_xyz789",
        "enabled": true,
        "cronExpression": "0 2 * * *"
      }
    ],
    "pitrConfigurations": [
      {
        "id": "pitr_def456",
        "projectId": "proj_xyz789",
        "enabled": true,
        "status": "active"
      }
    ],
    "backupsCount": 42
  }
}

Get Backups by Storage

Get all backups stored in a destination.

GET /api/v1/storage/destinations/:id/backups
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "backups": [
      {
        "id": "bkp_abc123",
        "projectId": "proj_xyz789",
        "projectName": "Production App",
        "status": "completed",
        "size": 6200000,
        "collections": ["users", "orders"],
        "createdAt": "2024-01-15T10:00:00Z",
        "storagePath": "backups/production/bkp_abc123.backup"
      }
    ],
    "totalCount": 42,
    "totalSize": 260400000
  }
}

Bulk Delete Backups

Delete multiple backups and optionally their storage files.

POST /api/v1/storage/destinations/:id/backups/bulk-delete
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "backupIds": ["bkp_abc123", "bkp_def456"],
  "deleteStorageFiles": true
}

Request Body:

Field	Type	Required	Description
`backupIds`	array	Yes	Backup IDs to delete
`deleteStorageFiles`	boolean	No	Also delete physical files

Response:

{
  "success": true,
  "message": "Deleted 2 of 2 backups and 2 storage files",
  "data": {
    "deletedCount": 2,
    "filesDeletedCount": 2,
    "failedCount": 0,
    "results": [
      { "backupId": "bkp_abc123", "deleted": true, "filesDeleted": true },
      { "backupId": "bkp_def456", "deleted": true, "filesDeleted": true }
    ]
  }
}

Admin Only

Only organization admins and owners can delete backups and storage files.

Migrate Resources

Migrate all linked resources to another storage destination.

POST /api/v1/storage/destinations/:id/migrate
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "targetStorageId": "storage_new456"
}

Response:

{
  "success": true,
  "data": {
    "schedulesUpdated": 3,
    "pitrConfigsUpdated": 1,
    "targetStorageId": "storage_new456",
    "targetStorageName": "New Production Storage"
  },
  "message": "Migrated 3 schedules and 1 PITR configurations to New Production Storage"
}

List Storage Files

List all files in a storage destination.

GET /api/v1/storage/destinations/:id/files
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
`force`	boolean	false	Force fresh scan (bypass cache)
`type`	string	-	Filter: `backup`, `meta`, `auth`, `pitr`, `unknown`
`orphansOnly`	boolean	false	Show only orphan files
`limit`	integer	-	Maximum files to return

Response:

{
  "success": true,
  "data": {
    "files": [
      {
        "path": "backups/production/bkp_abc123.backup",
        "size": "6200000",
        "lastModified": "2024-01-15T10:00:45Z",
        "backupId": "bkp_abc123",
        "projectId": "proj_xyz789",
        "projectName": "Production App",
        "type": "backup",
        "isOrphan": false
      },
      {
        "path": "backups/production/bkp_old999.backup",
        "size": "5500000",
        "lastModified": "2024-01-01T10:00:00Z",
        "type": "backup",
        "isOrphan": true
      }
    ],
    "total": 50,
    "totalSize": "310000000",
    "orphanSize": "5500000",
    "orphanCount": 1
  },
  "meta": {
    "cached": true,
    "lastSyncAt": "2024-01-15T10:00:00Z",
    "isFresh": true
  }
}

Get Storage Statistics

Get aggregated storage statistics for a destination.

GET /api/v1/storage/destinations/:id/files/stats
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
`force`	boolean	false	Force fresh calculation

Response:

{
  "success": true,
  "data": {
    "totalFiles": 150,
    "totalSize": "930000000",
    "linkedFiles": 145,
    "linkedSize": "900000000",
    "orphanFiles": 5,
    "orphanSize": "30000000",
    "byType": {
      "backup": { "count": 50, "size": "310000000" },
      "meta": { "count": 50, "size": "500000" },
      "auth": { "count": 45, "size": "450000000" },
      "pitr": { "count": 5, "size": "170000000" }
    }
  },
  "meta": {
    "cached": true,
    "lastSyncAt": "2024-01-15T10:00:00Z",
    "isFresh": true
  }
}

Delete Orphan File

Delete a single orphan file from storage.

DELETE /api/v1/storage/destinations/:id/files
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "path": "backups/production/bkp_old999.backup"
}

Response:

{
  "success": true,
  "message": "File deleted successfully",
  "data": {
    "deleted": true,
    "path": "backups/production/bkp_old999.backup"
  }
}

Orphan Files Only

Only orphan files (not associated with any backup record) can be deleted through this endpoint. Delete the backup record first to make its files orphans.

Bulk Delete Orphan Files

Delete multiple orphan files at once.

POST /api/v1/storage/destinations/:id/files/bulk-delete
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "paths": [
    "backups/production/bkp_old999.backup",
    "backups/production/bkp_old998.backup"
  ]
}

Response:

{
  "success": true,
  "message": "Deleted 2 of 2 files",
  "data": {
    "deletedCount": 2,
    "failedCount": 0,
    "results": [
      { "path": "backups/production/bkp_old999.backup", "deleted": true },
      { "path": "backups/production/bkp_old998.backup", "deleted": true }
    ]
  }
}

Cleanup All Orphans

Delete all orphan files in a storage destination.

POST /api/v1/storage/destinations/:id/cleanup-orphans
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Cleaned up 5 orphan files",
  "data": {
    "deletedCount": 5,
    "freedSpace": 30000000,
    "errors": []
  }
}

Get Organization Storage Stats

Get aggregated storage statistics across all destinations.

GET /api/v1/storage/stats
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
`force`	boolean	false	Force background sync

Response:

{
  "success": true,
  "data": {
    "destinations": [
      {
        "id": "storage_abc123",
        "name": "Production S3",
        "totalFiles": 150,
        "totalSize": "930000000",
        "orphanFiles": 5,
        "orphanSize": "30000000"
      }
    ],
    "totals": {
      "totalDestinations": 2,
      "totalFiles": 280,
      "totalSize": "1500000000",
      "orphanFiles": 8,
      "orphanSize": "45000000"
    },
    "lastFullSyncAt": "2024-01-15T10:00:00Z",
    "nextScheduledSyncAt": "2024-01-16T10:00:00Z"
  },
  "meta": {
    "isSyncing": false,
    "needsSync": false,
    "lastSyncAt": "2024-01-15T10:00:00Z",
    "nextScheduledSyncAt": "2024-01-16T10:00:00Z"
  }
}

Trigger Storage Sync

Manually trigger a storage sync operation.

POST /api/v1/storage/sync
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Description
`destinationId`	string	Sync only specific destination

Response:

{
  "success": true,
  "message": "Storage sync started. Subscribe to Socket.io events for progress updates.",
  "data": {
    "status": "syncing",
    "organizationId": "org_abc123"
  }
}

Real-time Updates

Subscribe to the storage:{organizationId} Socket.io room to receive:

storage:sync-progress - Progress updates during sync
storage:stats-update - Final stats when sync completes

Storage Destination Object

Field	Type	Description
`id`	string	Unique destination ID
`name`	string	Display name
`type`	string	Provider type
`bucket`	string	Bucket name
`path`	string	Base folder path
`region`	string	Bucket region
`verified`	boolean	Connection verified
`credentials`	object	Masked credentials
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Error Responses

Storage Not Found

{
  "success": false,
  "error": {
    "code": "STORAGE_NOT_FOUND",
    "message": "Storage destination not found"
  }
}

Invalid Credentials

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Failed to connect to storage provider",
    "details": {
      "provider": "S3",
      "reason": "The AWS Access Key Id you provided does not exist"
    }
  }
}

Bucket Not Found

{
  "success": false,
  "error": {
    "code": "BUCKET_NOT_FOUND",
    "message": "Bucket 'my-bucket' does not exist or is not accessible"
  }
}

Permission Denied

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Only admins and owners can delete storage files"
  }
}

File Not Orphan

{
  "success": false,
  "error": {
    "code": "FILE_NOT_ORPHAN",
    "message": "File is associated with a backup and cannot be deleted directly"
  }
}

Storage Configuration - User guide
Backups API - Backup operations
Schedules API - Automated backups

Endpoints Overview​

Connect to Storage Provider​

AWS S3​

Google Cloud Storage​

DigitalOcean Spaces​

Create Bucket​

Verify Bucket Access​

List Folders​

Create Folder​

List Storage Destinations​

Get Storage Destination​

Create Storage Destination​

Update Storage Destination​

Delete Storage Destination​

Verify Storage Destination​

Get Linked Resources​

Get Backups by Storage​

Bulk Delete Backups​

Migrate Resources​

List Storage Files​

Get Storage Statistics​

Delete Orphan File​

Bulk Delete Orphan Files​

Cleanup All Orphans​

Get Organization Storage Stats​

Trigger Storage Sync​

Storage Destination Object​

Error Responses​

Storage Not Found​

Invalid Credentials​

Bucket Not Found​

Permission Denied​

File Not Orphan​

Related​

Endpoints Overview

Connect to Storage Provider

AWS S3

Google Cloud Storage

DigitalOcean Spaces

Create Bucket

Verify Bucket Access

List Folders

Create Folder

List Storage Destinations

Get Storage Destination

Create Storage Destination

Update Storage Destination

Delete Storage Destination

Verify Storage Destination

Get Linked Resources

Get Backups by Storage

Bulk Delete Backups

Migrate Resources

List Storage Files

Get Storage Statistics

Delete Orphan File

Bulk Delete Orphan Files

Cleanup All Orphans

Get Organization Storage Stats

Trigger Storage Sync

Storage Destination Object

Error Responses

Storage Not Found

Invalid Credentials

Bucket Not Found

Permission Denied

File Not Orphan

Related