Backups API

Create, list, and restore backups via the REST API.

Endpoints Overview

List Backups

GET /api/v1/backups

Permission: backups:read

Query Parameters:

Example:

curl "https://supascale.example.com/api/v1/backups?projectId=my-project&limit=10" \
  -H "X-API-Key: your-key"

Response:

{
  "backups": [
    {
      "id": "backup-123",
      "projectId": "my-project",
      "projectName": "My Project",
      "type": "full",
      "status": "completed",
      "destination": "s3",
      "path": "s3://bucket/my-project/2026-01-19-full.tar.gz",
      "size": 52428800,
      "encrypted": false,
      "createdAt": "2026-01-19T02:00:00Z",
      "completedAt": "2026-01-19T02:02:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0
  }
}

With stats=true:

{
  "backups": [...],
  "stats": {
    "totalBackups": 45,
    "totalSize": 2362232012,
    "byDestination": {
      "local": { "count": 30, "size": 1073741824 },
      "s3": { "count": 15, "size": 1288490188 }
    }
  }
}

Create Backup

POST /api/v1/backups

Permission: backups:write

Request:

{
  "projectId": "my-project",
  "type": "full",
  "destination": "s3",
  "encrypt": false
}

Backup Types:

Destinations:

Response:

{
  "success": true,
  "backup": {
    "id": "backup-456",
    "projectId": "my-project",
    "type": "full",
    "status": "completed",
    "destination": "s3",
    "path": "s3://bucket/my-project/2026-01-19-full.tar.gz",
    "size": 52428800,
    "duration": 120,
    "createdAt": "2026-01-19T12:00:00Z"
  }
}

Get Backup Details

GET /api/v1/backups/:id

Permission: backups:read

Response:

{
  "id": "backup-123",
  "projectId": "my-project",
  "projectName": "My Project",
  "type": "full",
  "status": "completed",
  "destination": "s3",
  "path": "s3://bucket/my-project/2026-01-19-full.tar.gz",
  "size": 52428800,
  "encrypted": false,
  "createdAt": "2026-01-19T02:00:00Z",
  "completedAt": "2026-01-19T02:02:00Z",
  "restoreHistory": [
    {
      "restoredAt": "2026-01-19T10:00:00Z",
      "duration": 180
    }
  ]
}

Delete Backup

DELETE /api/v1/backups/:id

Permission: backups:write

Response:

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

Download Backup

GET /api/v1/backups/:id/download

Permission: backups:read

Returns the backup file as binary download.

Headers:

Content-Type: application/gzip
Content-Disposition: attachment; filename="my-project-2026-01-19-full.tar.gz"

Example:

curl https://supascale.example.com/api/v1/backups/backup-123/download \
  -H "X-API-Key: your-key" \
  -o backup.tar.gz

Restore Backup

POST /api/v1/backups/:id/restore

Permission: backups:write

Request:

{
  "restoreTypes": ["full"],
  "forceRestore": false
}

Restore Types:

Response:

{
  "success": true,
  "restore": {
    "backupId": "backup-123",
    "projectId": "my-project",
    "duration": 180,
    "restoredAt": "2026-01-19T12:00:00Z",
    "warnings": []
  }
}

With warnings:

{
  "success": true,
  "restore": {
    "backupId": "backup-123",
    "duration": 180,
    "warnings": [
      "Some functions could not be restored due to missing dependencies"
    ]
  }
}

Error Responses

Backup Not Found

{
  "success": false,
  "error": "Backup not found"
}

Status: 404

Project Not Found

{
  "success": false,
  "error": "Project not found"
}

Status: 400

Backup Failed

{
  "success": false,
  "error": "Backup failed: Insufficient disk space"
}

Status: 500

Restore Failed

{
  "success": false,
  "error": "Restore failed: Database connection error"
}

Status: 500

Backup Status Values