Repositories

Manage Borg backup repositories

Overview

Repository endpoints allow you to create, import, list, update, and delete Borg backup repositories.

List Repositories

Get all repositories with their metadata and status.

Endpoint: GET /api/repositories/

Example Request:

curl http://localhost:5000/api/repositories/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "success": true,
  "repositories": [
    {
      "id": 1,
      "name": "my-backup",
      "path": "/local/backups/my-repo",
      "encryption": "repokey",
      "compression": "lz4",
      "source_directories": ["/data", "/home"],
      "exclude_patterns": ["*.log", "*.tmp"],
      "repository_type": "local",
      "host": null,
      "port": null,
      "username": null,
      "ssh_key_id": null,
      "remote_path": null,
      "last_backup": "2024-01-15T10:30:00Z",
      "last_check": "2024-01-14T02:00:00Z",
      "last_compact": null,
      "total_size": "15.24 GB",
      "archive_count": 42,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "pre_backup_script": null,
      "post_backup_script": null,
      "hook_timeout": 300,
      "pre_hook_timeout": 300,
      "post_hook_timeout": 300,
      "continue_on_hook_failure": false,
      "mode": "full",
      "bypass_lock": false,
      "custom_flags": null,
      "has_running_maintenance": false,
      "has_keyfile": false,
      "source_ssh_connection_id": null
    }
  ]
}

Get Repository

Get details for a specific repository.

Endpoint: GET /api/repositories/{repo_id}

Example Request:

curl http://localhost:5000/api/repositories/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Repository

Initialize a new Borg repository.

Endpoint: POST /api/repositories/

Admin Only: Yes

name · string · required

Unique name for the repository

path · string · required

Path to repository (local path or will be constructed for SSH)

encryption · string · default: "repokey"

Encryption mode: repokey, keyfile, repokey-blake2, keyfile-blake2, or none

passphrase · string

Passphrase for encrypted repositories (required if encryption is not none)

compression · string · default: "lz4"

Compression algorithm: lz4, zstd, zlib, or none

source_directories · array

List of directories to back up (required for full mode)

exclude_patterns · array

List of exclude patterns (e.g., ["*.log", "*.tmp"])

connection_id · integer

SSH connection ID for remote repositories

remote_path · string

Path to borg binary on remote server (e.g., /usr/local/bin/borg)

mode · string · default: "full"

Repository mode: full (backups + observability) or observe (read-only observability)

bypass_lock · boolean · default: false

Use --bypass-lock for read-only access (observe mode only)

custom_flags · string

Custom command-line flags for borg create (e.g., "--stats --list")

source_connection_id · integer

SSH connection ID for remote data source (pull-based backups)

pre_backup_script · string

Script to run before backup

post_backup_script · string

Script to run after backup

pre_hook_timeout · integer · default: 300

Pre-backup hook timeout in seconds

post_hook_timeout · integer · default: 300

Post-backup hook timeout in seconds

continue_on_hook_failure · boolean · default: false

Continue backup if pre-hook fails

Example Request:

curl -X POST http://localhost:5000/api/repositories/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-backup",
    "path": "/local/backups/my-repo",
    "encryption": "repokey",
    "passphrase": "strong-passphrase",
    "compression": "lz4",
    "source_directories": ["/data", "/home"],
    "exclude_patterns": ["*.log", "*.tmp"],
    "mode": "full"
  }'

Response:

{
  "success": true,
  "message": "Repository created successfully",
  "repository": {
    "id": 1,
    "name": "my-backup",
    "path": "/local/backups/my-repo",
    "encryption": "repokey",
    "compression": "lz4"
  }
}

Import Repository

Import an existing Borg repository.

Endpoint: POST /api/repositories/import

Admin Only: Yes

name · string · required

Unique name for the repository

path · string · required

Path to existing repository

passphrase · string

Passphrase if repository is encrypted

compression · string · default: "lz4"

Compression for future backups

source_directories · array

Directories to back up (required for full mode)

keyfile_content · string

Content of borg keyfile for keyfile-based encryption

Example Request:

curl -X POST http://localhost:5000/api/repositories/import \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-backup",
    "path": "ssh://user@host:22/backups/repo",
    "passphrase": "existing-passphrase",
    "connection_id": 1,
    "mode": "observe"
  }'

Update Repository

Update repository settings.

Endpoint: PUT /api/repositories/{repo_id}

Admin Only: Yes

Example Request:

curl -X PUT http://localhost:5000/api/repositories/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-name",
    "source_directories": ["/data", "/home", "/var"]
  }'

Delete Repository

Delete a repository from Borg UI (does not delete actual Borg repository).

Endpoint: DELETE /api/repositories/{repo_id}

Admin Only: Yes

Example Request:

curl -X DELETE http://localhost:5000/api/repositories/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Keyfile Management

Upload Keyfile

Upload a keyfile for repositories using keyfile encryption.

Endpoint: POST /api/repositories/{repo_id}/keyfile

Admin Only: Yes

Example Request:

curl -X POST http://localhost:5000/api/repositories/1/keyfile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "keyfile=@/path/to/keyfile"

Download Keyfile

Export and download the keyfile for a repository.

Endpoint: GET /api/repositories/{repo_id}/keyfile

Admin Only: Yes

Example Request:

curl http://localhost:5000/api/repositories/1/keyfile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o keyfile