Archives

List, inspect, and manage backup archives

Overview

Archive endpoints allow you to list archives in a repository, view detailed information, browse contents, delete archives, and extract files.

List Archives

List all archives in a repository.

Endpoint: GET /api/archives/list

repository · string · required

Repository path

Example Request:

curl "http://localhost:5000/api/archives/list?repository=/local/backups/my-repo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "archives": {
    "archives": [
      {
        "name": "backup-2024-01-15T10:30:00",
        "id": "abc123def456",
        "start": "2024-01-15T10:30:00",
        "time": "2024-01-15T10:30:00"
      },
      {
        "name": "backup-2024-01-14T02:00:00",
        "id": "def456ghi789",
        "start": "2024-01-14T02:00:00",
        "time": "2024-01-14T02:00:00"
      }
    ]
  }
}

Get Archive Info

Get detailed information about a specific archive.

Endpoint: GET /api/archives/{archive_id}/info

repository · string · required

Repository path

include_files · boolean · default: false

Include file listing in response

file_limit · integer · default: 1000

Maximum number of files to return if include_files is true

Example Request:

curl "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00/info?repository=/local/backups/my-repo&include_files=true&file_limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "info": {
    "name": "backup-2024-01-15T10:30:00",
    "id": "abc123def456",
    "start": "2024-01-15T10:30:00",
    "end": "2024-01-15T10:45:30",
    "duration": 930.5,
    "stats": {
      "original_size": 10737418240,
      "compressed_size": 8589934592,
      "deduplicated_size": 2147483648,
      "nfiles": 15420
    },
    "command_line": [
      "borg",
      "create",
      "--stats",
      "--json",
      "--compression",
      "lz4"
    ],
    "hostname": "server01",
    "username": "root",
    "chunker_params": "19,23,21,4095",
    "limits": {
      "max_archive_size": 0
    },
    "comment": "",
    "repository": {
      "id": "repo123",
      "location": "/local/backups/my-repo"
    },
    "encryption": {
      "mode": "repokey-blake2"
    },
    "cache": {
      "path": "/root/.cache/borg/abc123",
      "stats": {
        "total_chunks": 52341,
        "total_csize": 8589934592,
        "unique_chunks": 12456,
        "unique_csize": 2147483648
      }
    },
    "files": [
      {
        "path": "/data/file1.txt",
        "type": "file",
        "mode": "rw-r--r--",
        "user": "root",
        "group": "root",
        "size": 4096,
        "mtime": "2024-01-15T09:00:00",
        "healthy": true
      }
    ],
    "file_count": 100
  }
}

info.stats.original_size · integer

Original size in bytes before compression

info.stats.compressed_size · integer

Size after compression in bytes

info.stats.deduplicated_size · integer

Actual storage used after deduplication in bytes

info.stats.nfiles · integer

Number of files in the archive

info.command_line · array

Command used to create the archive

info.hostname · string

Hostname where backup was created

info.files · array

Array of file objects (only if include_files=true)

Get Archive Contents

List files and directories in an archive.

Endpoint: GET /api/archives/{archive_id}/contents

repository · string · required

Repository path

path · string · default: ""

Subdirectory path to list (empty for root)

Example Request:

curl "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00/contents?repository=/local/backups/my-repo&path=/data" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "contents": [
    {
      "path": "/data/file1.txt",
      "type": "file",
      "mode": "rw-r--r--",
      "user": "root",
      "group": "root",
      "size": 4096,
      "mtime": "2024-01-15T09:00:00"
    },
    {
      "path": "/data/subdir",
      "type": "directory",
      "mode": "rwxr-xr-x",
      "user": "root",
      "group": "root",
      "size": 0,
      "mtime": "2024-01-15T09:00:00"
    }
  ]
}

Delete Archive

Delete an archive from the repository (runs in background).

Endpoint: DELETE /api/archives/{archive_id}

Admin Only: Yes

repository · string · required

Repository path

Example Request:

curl -X DELETE "http://localhost:5000/api/archives/backup-2024-01-15T10:30:00?repository=/local/backups/my-repo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "job_id": 456,
  "status": "pending",
  "message": "Archive deletion started in background"
}

job_id · integer

ID of the delete job for status monitoring

Get Delete Job Status

Monitor the status of an archive deletion.

Endpoint: GET /api/archives/delete-jobs/{job_id}

Example Request:

curl http://localhost:5000/api/archives/delete-jobs/456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": 456,
  "repository_id": 1,
  "archive_name": "backup-2024-01-15T10:30:00",
  "status": "completed",
  "started_at": "2024-01-15T11:00:00Z",
  "completed_at": "2024-01-15T11:05:30Z",
  "progress": 100,
  "progress_message": "Archive deleted successfully",
  "error_message": null,
  "logs": null,
  "has_logs": false
}

Cancel Delete Job

Cancel a running archive deletion.

Endpoint: POST /api/archives/delete-jobs/{job_id}/cancel

Admin Only: Yes

Example Request:

curl -X POST http://localhost:5000/api/archives/delete-jobs/456/cancel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "Delete job cancelled successfully"
}

Download File from Archive

Extract and download a specific file from an archive.

Endpoint: GET /api/archives/download

repository · string · required

Repository path

archive · string · required

Archive name

file_path · string · required

Path to file within archive

token · string · required

Access token (passed as query parameter for download links)

Example Request:

curl "http://localhost:5000/api/archives/download?repository=/local/backups/my-repo&archive=backup-2024-01-15T10:30:00&file_path=/data/file1.txt&token=YOUR_ACCESS_TOKEN" \
  -o file1.txt

Response: Binary file content with appropriate Content-Type header

Archive Status Values

Delete jobs can have the following statuses:

• pending - Job created, waiting to start
• running - Deletion in progress
• completed - Deletion completed successfully
• failed - Deletion failed with errors
• cancelled - Deletion was cancelled