Backups

Create and monitor backup operations

Overview

Backup endpoints allow you to start manual backups, monitor progress, view job history, and cancel running operations.

Start Backup

Start a manual backup operation.

Endpoint: POST /api/backup/start

repository · string · required

Repository path to back up

Example Request:

curl -X POST http://localhost:5000/api/backup/start \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "/local/backups/my-repo"
  }'

Response:

{
  "job_id": 123,
  "status": "pending",
  "message": "Backup job started"
}

job_id · integer

ID of the created backup job

status · string

Initial job status: pending

message · string

Human-readable message

Get All Backup Jobs

Retrieve backup job history with progress details.

Endpoint: GET /api/backup/jobs

limit · integer · default: 200

Maximum number of jobs to return

scheduled_only · boolean · default: false

Only return jobs triggered by scheduled tasks

manual_only · boolean · default: false

Only return manual backup jobs

Example Request:

curl "http://localhost:5000/api/backup/jobs?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "jobs": [
    {
      "id": 123,
      "repository": "/local/backups/my-repo",
      "status": "completed",
      "started_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:15:30Z",
      "progress": 100,
      "error_message": null,
      "has_logs": false,
      "maintenance_status": null,
      "scheduled_job_id": null,
      "progress_details": {
        "original_size": 10737418240,
        "compressed_size": 8589934592,
        "deduplicated_size": 2147483648,
        "nfiles": 15420,
        "current_file": "",
        "progress_percent": 100,
        "backup_speed": 125.5,
        "total_expected_size": 10737418240,
        "estimated_time_remaining": 0
      }
    }
  ]
}

jobs · array

Array of backup job objects

jobs[].status · string

Job status: pending, running, completed, completed_with_warnings, failed, or cancelled

jobs[].progress_details.original_size · integer

Original size in bytes before compression

jobs[].progress_details.compressed_size · integer

Compressed size in bytes

jobs[].progress_details.deduplicated_size · integer

Deduplicated size in bytes (actual storage used)

jobs[].progress_details.nfiles · integer

Number of files processed

jobs[].progress_details.backup_speed · number

Backup speed in MB/s

Get Backup Status

Get detailed status for a specific backup job.

Endpoint: GET /api/backup/status/{job_id}

Example Request:

curl http://localhost:5000/api/backup/status/123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": 123,
  "repository": "/local/backups/my-repo",
  "status": "running",
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": null,
  "progress": 65,
  "error_message": null,
  "logs": null,
  "maintenance_status": null,
  "progress_details": {
    "original_size": 7000000000,
    "compressed_size": 5600000000,
    "deduplicated_size": 1400000000,
    "nfiles": 10023,
    "current_file": "/data/documents/report.pdf",
    "progress_percent": 65,
    "backup_speed": 125.5,
    "total_expected_size": 10737418240,
    "estimated_time_remaining": 180
  }
}

Cancel Backup

Cancel a running backup job.

Endpoint: POST /api/backup/cancel/{job_id}

Example Request:

curl -X POST http://localhost:5000/api/backup/cancel/123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Backup cancelled successfully",
  "process_terminated": true
}

process_terminated · boolean

Whether the backup process was successfully terminated

Stream Backup Logs

Get incremental logs for real-time streaming (for failed/cancelled backups only).

Endpoint: GET /api/backup/logs/{job_id}/stream

offset · integer · default: 0

Line number to start from for incremental updates

Example Request:

curl "http://localhost:5000/api/backup/logs/123/stream?offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "job_id": 123,
  "status": "failed",
  "lines": [
    {
      "line_number": 1,
      "content": "Starting backup operation..."
    },
    {
      "line_number": 2,
      "content": "Error: Repository locked by another process"
    }
  ],
  "total_lines": 2,
  "has_more": false
}

Download Backup Logs

Download complete logs as a text file (for failed/cancelled backups only).

Endpoint: GET /api/backup/logs/{job_id}/download

token · string · required

Access token (passed as query parameter for download links)

Example Request:

curl "http://localhost:5000/api/backup/logs/123/download?token=YOUR_ACCESS_TOKEN" \
  -o backup_logs.txt

Response: Plain text file with complete backup logs

Progress Tracking

Backup progress is tracked in real-time with the following metrics:

• Progress Percent: Overall completion percentage (0-100)
• Original Size: Total size of data being backed up
• Compressed Size: Size after compression
• Deduplicated Size: Actual storage used after deduplication
• Files Processed: Number of files backed up
• Current File: File currently being processed
• Backup Speed: Current throughput in MB/s
• Estimated Time Remaining: Seconds until completion

Status Values

Backup jobs can have the following statuses:

• pending - Job created, waiting to start
• running - Backup in progress
• completed - Backup completed successfully
• completed_with_warnings - Backup completed but with warnings
• failed - Backup failed with errors
• cancelled - Backup was cancelled by user

Maintenance Operations

Backups can include automatic maintenance:

• Prune: Remove old archives based on retention policy
• Compact: Free up space by compacting repository segments

Maintenance status is tracked in the maintenance_status field.