Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us