### Run the BBS Installer

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Execute the automated installation script for a standard internet-connected setup with automatic SSL.

```bash
curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install | sudo bash
```

--------------------------------

### Create Client API Response Example

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Example JSON response upon successful client creation. It includes the new client's ID, name, API key, status, and the command to install the agent.

```json
{
  "id": 42,
  "name": "web-server-01",
  "api_key": "a5b8c9d0e1f2...",
  "status": "setup",
  "install_command": "curl -s https://your-server/get-agent | sudo bash -s -- --server https://your-server --key a5b8c9d0e1f2..."
}
```

--------------------------------

### Access Setup Wizard URL

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Access the setup wizard in your web browser after installation. Use the HTTPS URL for standard installations or HTTP with the server's IP for LAN setups.

```text
https://backups.example.com/setup
```

```text
http://your-server-ip/setup
```

--------------------------------

### Install BBS on a new server

Source: https://github.com/marcpope/borgbackupserver/wiki/S3-Offsite-Sync

Execute the installation script to set up a fresh BBS instance.

```bash
sudo bash bbs-install
```

--------------------------------

### Install BorgBackupServer on Ubuntu

Source: https://github.com/marcpope/borgbackupserver/blob/main/README.md

Use this script for a quick installation on Ubuntu 22.04+. The installer configures packages, web server, database, SSL, and cron jobs.

```bash
curl -sO https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install
sudo bash bbs-install --hostname backups.example.com
```

--------------------------------

### Install with Custom Hostname

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Download and run the installer script with a specific hostname argument.

```bash
curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install -o bbs-install
chmod +x bbs-install
sudo ./bbs-install --hostname backups.example.com
```

--------------------------------

### Install BBS Server

Source: https://github.com/marcpope/borgbackupserver/wiki/CLI-Reference

Use the installer script to set up BBS on a fresh Ubuntu 22.04+ server.

```bash
sudo bash bbs-install [--hostname HOST] [--no-ssl]
```

```bash
# Interactive installation with prompts
sudo bash bbs-install

# Automated installation with hostname
sudo bash bbs-install --hostname bbs.example.com

# LAN installation without SSL
sudo bash bbs-install --hostname bbs.local --no-ssl
```

--------------------------------

### Install Pip on Client

Source: https://github.com/marcpope/borgbackupserver/wiki/Updating-BBS

Install the python3-pip package on the client machine.

```bash
sudo apt install python3-pip
```

--------------------------------

### Install BorgBackup and Python 3 via Homebrew

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

After installing Homebrew, use this command to install the necessary packages for the BBS agent. The agent installer can also attempt this automatically.

```bash
brew install borgbackup python3
```

--------------------------------

### BBS Windows Agent Installer Output

Source: https://github.com/marcpope/borgbackupserver/wiki/Windows-Agent-Setup

This output shows the successful installation process of the BBS Windows agent, including connectivity checks, Borg for Windows installation, service setup, and startup.

```text
  ================================================================
    Borg Backup Server - Windows Agent Installer
  ================================================================

  -> Checking server connectivity...
  [OK] Server reachable
  -> Finding latest Borg for Windows release...
  [OK] Latest release: v1.4.4-win5
  -> Downloading v1.4.4-win5...
  [OK] Downloaded borg-windows.zip
  -> Installing Borg to C:\Program Files\BorgBackup...
  [OK] Installed: borg.exe 1.4.4
  -> Adding Borg to system PATH...
  [OK] Added to system PATH
  -> Downloading agent launcher...
  [OK] Downloaded bbs-agent.exe
  -> Downloading agent script...
  [OK] Downloaded bbs-agent-run.py
  [OK] Python already installed: Python 3.11.4
  -> Writing configuration...
  [OK] Config written
  -> Downloading SSH key...
  [OK] SSH key saved
  -> Installing Windows Service...
  [OK] Service 'BorgBackupAgent' installed
  -> Starting service...
  [OK] Service is running

  ================================================================
    Installation Complete!
  ================================================================
```

--------------------------------

### Install BorgBackupServer Agent

Source: https://github.com/marcpope/borgbackupserver/wiki/Linux-Agent-Setup

Run this command on the client machine to download and install the agent. Replace placeholders with your BBS server URL and API key.

```bash
# Simple 1 Line Install:
curl -s https://backup.mydomain.com/get-agent | sudo bash -s -- --server https://beta.borgbackupserver.com --key YOUR_API_KEY
```

--------------------------------

### Install for LAN (No SSL)

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Run the installer without SSL configuration for private network environments.

```bash
curl -sSL https://raw.githubusercontent.com/marcpope/borgbackupserver/main/bin/bbs-install -o bbs-install
chmod +x bbs-install
sudo ./bbs-install --no-ssl
```

--------------------------------

### Download Docker Compose and Environment Files

Source: https://github.com/marcpope/borgbackupserver/wiki/Docker-Installation

Download the necessary Docker Compose file and an example environment file. Copy the example to a new file to configure your BBS instance.

```bash
curl -sO https://raw.githubusercontent.com/marcpope/borgbackupserver/main/docker-compose.yml
curl -sO https://raw.githubusercontent.com/marcpope/borgbackupserver/main/.env.example
cp .env.example .env
```

--------------------------------

### Access BBS Setup on LAN

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Access the BBS setup wizard via HTTP using the server's IP address for LAN installations. This is used when SSL is not configured.

```text
http://192.168.1.100/setup
```

--------------------------------

### Full Ansible Workflow for BorgBackupServer Setup

Source: https://github.com/marcpope/borgbackupserver/wiki/API

This snippet outlines a comprehensive Ansible playbook to automate the entire BorgBackupServer setup process, from initial token generation to creating complex backup plans with plugins.

```yaml
# 1. Generate API token (run once after BBS install)
- name: Generate BBS admin API token
  command: /var/www/bbs/bin/bbs-token create --name "ansible"
  register: bbs_token
  delegate_to: backup_server

# 2. Create client
- name: Create BBS client
  uri:
    url: "https://backup.example.com/api/v1/clients"
    method: POST
    headers:
      Authorization: "Bearer {{ bbs_token.stdout }}"
    body_format: json
    body:
      name: "{{ inventory_hostname }}"
  register: bbs_client

# 3. Install agent
- name: Install BBS agent
  shell: "{{ bbs_client.json.install_command }}"
  args:
    creates: /etc/bbs-agent/config.ini

# 4. Create repository
- name: Create repository
  uri:
    url: "https://backup.example.com/api/v1/clients/{{ bbs_client.json.id }}/repositories"
    method: POST
    headers:
      Authorization: "Bearer {{ bbs_token.stdout }}"
    body_format: json
    body:
      name: "{{ inventory_hostname }}-main"
      encryption: repokey-blake2
  register: bbs_repo

# 5. Create MySQL plugin config
- name: Configure MySQL backup
  uri:
    url: "https://backup.example.com/api/v1/clients/{{ bbs_client.json.id }}/plugin-configs"
    method: POST
    headers:
      Authorization: "Bearer {{ bbs_token.stdout }}"
    body_format: json
    body:
      plugin: mysql_dump
      name: "Production DB"
      config:
        host: localhost
        user: bbs_backup
        password: "{{ mysql_backup_password }}"
        databases: "*"
        dump_dir: /home/bbs/mysql
  register: mysql_config

# 6. Create backup plan with MySQL plugin
- name: Create backup plan
  uri:
    url: "https://backup.example.com/api/v1/clients/{{ bbs_client.json.id }}/plans"
    method: POST
    headers:
      Authorization: "Bearer {{ bbs_token.stdout }}"
    body_format: json
    body:
      name: daily-backup
      repository_id: "{{ bbs_repo.json.id }}"
      directories: "/home\n/etc\n/var/www"
      excludes: "*.tmp\n*.log\n*.cache"
      advanced_options: "--compression lz4 --exclude-caches --noatime"
      frequency: daily
      times: "02:00"
      prune_days: 7
      prune_weeks: 4
      prune_months: 6
      plugins:
        - plugin_config_id: "{{ mysql_config.json.id }}"
```

--------------------------------

### Deploy BorgBackupServer with Docker Compose

Source: https://github.com/marcpope/borgbackupserver/blob/main/README.md

Deploy BorgBackupServer using pre-built Docker images. This method simplifies setup and management. Ensure Docker and Docker Compose are installed.

```bash
curl -sO https://raw.githubusercontent.com/marcpope/borgbackupserver/main/docker-compose.yml
docker compose up -d
```

--------------------------------

### Install BBS on New Server

Source: https://github.com/marcpope/borgbackupserver/wiki/Server-Backup-and-Restore

Install BBS on a new server, specifying the hostname. This is the first step in a bare metal restore process.

```bash
sudo bash bbs-install --hostname backup.example.com
```

--------------------------------

### Example Migration File Structure

Source: https://github.com/marcpope/borgbackupserver/wiki/Updating-BBS

Illustrates the directory structure and naming convention for database migration SQL files.

```bash
migrations/
├── 2024-01-10_add_plugins_table.sql
├── 2024-01-15_add_2fa_columns.sql
└── 2024-01-20_add_s3_sync_config.sql
```

--------------------------------

### Get PHP Version

Source: https://github.com/marcpope/borgbackupserver/wiki/Troubleshooting

Display the installed PHP version.

```bash
php -v
```

--------------------------------

### Get MySQL Version

Source: https://github.com/marcpope/borgbackupserver/wiki/Troubleshooting

Display the installed MySQL version.

```bash
mysql --version
```

--------------------------------

### Pip Install BorgBackup Command

Source: https://github.com/marcpope/borgbackupserver/wiki/Updating-BBS

Use this command to install or update BorgBackup via pip. Ensure Python 3.6+ and pip are installed.

```bash
pip3 install borgbackup=={version}
```

--------------------------------

### Start BBS Agent Service

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

Manually start the BBS Agent service by bootstrapping its launchd definition. This is typically used after stopping the service or if it failed to start on boot.

```bash
sudo launchctl bootstrap system /Library/LaunchDaemons/com.borgbackupserver.agent.plist
```

--------------------------------

### Install Homebrew on macOS

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

Run this command in Terminal to install Homebrew if it's not already present. Homebrew is required for installing BorgBackup and Python 3.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Install Apprise for Push Notifications

Source: https://github.com/marcpope/borgbackupserver/wiki/Notifications

Install the Apprise library using pip to enable push notifications. This is required on the BBS server.

```bash
pip3 install apprise
```

--------------------------------

### Create Database Manually

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Use this command to create the required database if the setup wizard fails to connect.

```bash
sudo mysql -e "CREATE DATABASE IF NOT EXISTS bbs;"
```

--------------------------------

### Check Apprise Installation

Source: https://github.com/marcpope/borgbackupserver/wiki/Notifications

Verify if Apprise is installed on the BBS server by running the 'which apprise' command.

```bash
which apprise
```

--------------------------------

### Start Development Environment with Docker

Source: https://github.com/marcpope/borgbackupserver/blob/main/CONTRIBUTING.md

Use this command to quickly spin up the project environment using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Install and Verify Dependencies

Source: https://github.com/marcpope/borgbackupserver/wiki/Updating-BBS

Commands to reinstall composer and verify required PHP extensions.

```bash
sudo apt install composer
```

```bash
php -m | grep -E 'pdo|mysql|mbstring|curl'
```

```bash
cd /var/www/bbs && sudo composer install
```

--------------------------------

### Install BBS Agent on macOS

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

Paste this command into your Mac's Terminal, replacing placeholders with your BBS server URL and API key. This command downloads and installs the agent, configures it, and sets up the system service.

```bash
curl -s https://your-bbs-server.com/get-agent | sudo bash -s -- \
    --server https://your-bbs-server.com \
    --key YOUR_API_KEY
```

--------------------------------

### Start BBS Agent Service

Source: https://github.com/marcpope/borgbackupserver/wiki/Troubleshooting

If the agent service has stopped, start it using systemctl.

```bash
sudo systemctl start bbs-agent
```

--------------------------------

### BBS Agent Configuration Example

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

Example INI file for configuring the BBS Agent. Set the server URL and API key, and optionally adjust the polling interval.

```ini
[server]
url = https://your-bbs-server.com
api_key = abc123...

[agent]
poll_interval = 30
```

--------------------------------

### List Clients API Response Example

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Example JSON response when listing clients. It shows the structure of client data returned by the API.

```json
{
  "clients": [
    {
      "id": 1,
      "name": "web-server-01",
      "hostname": "web01.example.com",
      "ip_address": "10.0.1.5",
      "status": "online",
      "agent_version": "2.18.7",
      "borg_version": "1.4.3",
      "last_heartbeat": "2026-03-30 12:00:00",
      "created_at": "2026-03-01 10:00:00",
      "owner": "admin"
    }
  ]
}
```

--------------------------------

### Create Client

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Creates a new client on the BorgBackup Server. Returns the client's API key and installation command.

```APIDOC
## POST /api/v1/clients

### Description
Creates a new client on the BorgBackup Server. The `api_key` is used for agent authentication, and the `install_command` can be used to deploy the agent.

### Method
POST

### Endpoint
/api/v1/clients

### Parameters
#### Request Body
- **name** (string) - Required - The desired name for the new client.

### Request Example
{
  "name": "web-server-01"
}

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier for the newly created client.
- **name** (string) - The name of the client.
- **api_key** (string) - The API key for the agent to authenticate with the server.
- **status** (string) - The initial status of the client (e.g., "setup").
- **install_command** (string) - The command to execute on the client machine to install the agent.

### Response Example
{
  "id": 42,
  "name": "web-server-01",
  "api_key": "a5b8c9d0e1f2...",
  "status": "setup",
  "install_command": "curl -s https://your-server/get-agent | sudo bash -s -- --server https://your-server --key a5b8c9d0e1f2..."
}
```

--------------------------------

### Install Agent on LAN Client

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Use this command to register a client with the backup server using the provided API key.

```bash
sudo python3 bbs-agent.py --server http://192.168.1.100 --api-key YOUR_API_KEY
```

--------------------------------

### Get Ubuntu Version

Source: https://github.com/marcpope/borgbackupserver/wiki/Troubleshooting

Display the Ubuntu version information.

```bash
lsb_release -a
```

--------------------------------

### Create Client API Request Body Example

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Example JSON payload for creating a new client. Only the 'name' field is mandatory.

```json
{
  "name": "web-server-01"
}
```

--------------------------------

### Create Plugin Configuration

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Set up a new plugin configuration for a client. This example shows configuration for a MySQL dump plugin.

```http
POST /api/v1/clients/{id}/plugin-configs
```

```json
{
  "plugin": "mysql_dump",
  "name": "Production MySQL",
  "config": {
    "host": "localhost",
    "port": 3306,
    "user": "bbs_backup",
    "password": "secret123",
    "databases": "*",
    "dump_dir": "/home/bbs/mysql",
    "compress": true,
    "cleanup_after": true
  }
}
```

```json
{
  "id": 12,
  "plugin": "mysql_dump",
  "name": "Production MySQL"
}
```

--------------------------------

### Microsoft 365 SMTP Configuration Example

Source: https://github.com/marcpope/borgbackupserver/wiki/Notifications

Example SMTP settings for sending emails via Microsoft 365.

```text
SMTP Host: smtp.office365.com
SMTP Port: 587
Encryption: TLS
Username: your-email@yourdomain.com
Password: your-password
```

--------------------------------

### Install Windows Agent with PowerShell

Source: https://github.com/marcpope/borgbackupserver/wiki/Windows-Agent-Setup

Use this command in an Administrator PowerShell or Command Prompt to download and install the BBS agent. Ensure you replace 'https://your-server.com' and 'YOUR_API_KEY' with your actual server address and API key.

```powershell
powershell -ExecutionPolicy Bypass -Command "& {iwr -UseBasicParsing 'https://your-server.com/api/agent/download?file=install-windows.ps1' -OutFile $env:TEMP\bbs-install.ps1; & $env:TEMP\bbs-install.ps1 -Server 'https://your-server.com' -Key 'YOUR_API_KEY'}"
```

--------------------------------

### BBS Update Script Output

Source: https://github.com/marcpope/borgbackupserver/wiki/Updating-BBS

Example output showing the update process from version 0.9.3-beta to 0.9.4-beta.

```text
BBS Update Script
=================
Checking for updates...
Current version: 0.9.3-beta
Latest version: 0.9.4-beta
Update available!

Fetching updates from GitHub...
Checking out v0.9.4-beta...
Installing dependencies...
Running migrations...
Migration 2024-01-15_add_2fa.sql applied.
Fixing permissions...
Restarting PHP-FPM...
Update complete!

Current version: 0.9.4-beta
```

--------------------------------

### Perform Disaster Recovery

Source: https://github.com/marcpope/borgbackupserver/wiki/CLI-Reference

Steps for installing BorgBackupServer on a new server, transferring a backup, and restoring it.

```bash
# 1. Install on new server
sudo bash bbs-install --hostname bbs.example.com
```

```bash
# 2. Transfer backup
scp backup.tar.gz root@newserver:/tmp/
```

```bash
# 3. Restore
sudo /var/www/bbs/bin/bbs-restore /tmp/backup.tar.gz
```

--------------------------------

### Resolve Package Installation Failures

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Update system repositories and packages before re-running the installer if apt errors occur.

```bash
sudo apt update
sudo apt upgrade
sudo ./bbs-install
```

--------------------------------

### Production Configuration Example

Source: https://github.com/marcpope/borgbackupserver/wiki/Docker-Installation

Configure for a production server with a real hostname and HTTPS. This assumes a reverse proxy handles SSL termination.

```ini
APP_URL=https://backups.example.com
WEB_PORT=443
SSH_PORT=2222
```

--------------------------------

### Enable Podman Container Auto-start

Source: https://github.com/marcpope/borgbackupserver/wiki/Docker-Installation

Enable systemd user services for Podman containers to start automatically on login.

```bash
loginctl enable-linger
systemctl --user daemon-reload
systemctl --user start borgbackupserver
```

--------------------------------

### SendGrid SMTP Configuration Example

Source: https://github.com/marcpope/borgbackupserver/wiki/Notifications

Example SMTP settings for sending emails via SendGrid. Use 'apikey' as the username.

```text
SMTP Host: smtp.sendgrid.net
SMTP Port: 587
Encryption: TLS
Username: apikey
Password: YOUR_SENDGRID_API_KEY
```

--------------------------------

### Install BorgBackup Server without SSL

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

Use this command to install BorgBackup Server on an isolated LAN without public DNS or internet access. It skips SSL certificate generation and HTTPS configuration.

```bash
sudo ./bbs-install --no-ssl
```

--------------------------------

### Install Borg on Hetzner Storage Box

Source: https://github.com/marcpope/borgbackupserver/wiki/Remote-Storage

Installs Borg on a Hetzner Storage Box if it's not pre-installed. Ensure you are connected via SSH on port 23.

```bash
ssh -p 23 uXXXXXX@uXXXXXX.your-storagebox.de borg --version
```

--------------------------------

### Gmail SMTP Configuration Example

Source: https://github.com/marcpope/borgbackupserver/wiki/Notifications

Example SMTP settings for sending emails via Gmail. Note that an App Password is required if 2FA is enabled.

```text
SMTP Host: smtp.gmail.com
SMTP Port: 587
Encryption: TLS
Username: your-email@gmail.com
Password: your-app-password (not regular password)
```

--------------------------------

### Mount NFS Share on Bare Metal or VM

Source: https://github.com/marcpope/borgbackupserver/wiki/Storage-Setup

Install the NFS client, create a mount point, mount the share, and add it to fstab for persistence.

```bash
# Install NFS client
apt install nfs-common

# Create mount point
mkdir -p /mnt/nfs-backup

# Mount (replace with your NFS server IP and export path)
mount -t nfs 192.168.1.100:/volume1/bbs-storage /mnt/nfs-backup

# Verify it works
touch /mnt/nfs-backup/test && rm /mnt/nfs-backup/test && echo "Mount OK"

# Add to /etc/fstab for persistence
echo "192.168.1.100:/volume1/bbs-storage  /mnt/nfs-backup  nfs  defaults,_netdev  0  0" >> /etc/fstab
```

--------------------------------

### BBS Directory Structure

Source: https://github.com/marcpope/borgbackupserver/wiki/Installation

The standard directory layout created by the installation script.

```text
/var/www/bbs/          # Application root
/var/www/bbs/config/   # Configuration files
/var/bbs/home/         # Borg repository storage (default)
/var/log/bbs/          # Log files
```

--------------------------------

### Example Post-backup Script with Webhook

Source: https://github.com/marcpope/borgbackupserver/wiki/Plugins

This script restarts services after a backup and sends a webhook notification with the backup status. It handles 'completed', 'warning', and 'failed' states.

```bash
#!/usr/bin/env bash
# Always restart services regardless of backup outcome
systemctl start nginx

# Send notification with the actual outcome
case "$BBS_BACKUP_STATUS" in
    completed)
        curl -fsS -X POST https://monitoring.example.com/webhook \
            -d "status=ok&archive=$BBS_ARCHIVE_NAME&plan=$BBS_BACKUP_PLAN"
        ;;;;
    warning)
        curl -fsS -X POST https://monitoring.example.com/webhook \
            -d "status=warning&archive=$BBS_ARCHIVE_NAME&plan=$BBS_BACKUP_PLAN"
        ;;;;
    failed)
        curl -fsS -X POST https://monitoring.example.com/webhook \
            -d "status=failed&client=$BBS_CLIENT_NAME&plan=$BBS_BACKUP_PLAN"
        ;;;;
esac
```

--------------------------------

### Configure Retention Policy

Source: https://github.com/marcpope/borgbackupserver/wiki/Backup-Plans

Example configuration for defining how many archives to keep per time interval.

```text
Keep last 7 days: 7
Keep last 4 weeks: 4
Keep last 6 months: 6
```

--------------------------------

### Update Client API Request Body Example

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Example JSON payload for updating a client. You can change the client's name by providing it in the request body.

```json
{
  "name": "new-client-name"
}
```

--------------------------------

### Interactive Restore Prompts

Source: https://github.com/marcpope/borgbackupserver/wiki/CLI-Reference

Example of the interactive prompts encountered during the restoration process.

```text
Restore config/.env? (y/n): y
Restore database? (y/n): y
```

--------------------------------

### Database Query Examples

Source: https://github.com/marcpope/borgbackupserver/blob/main/CLAUDE.md

Common database operations including fetching, inserting, updating, and deleting records.

```php
$this->db->fetchOne();
$this->db->fetchAll();
$this->db->insert();
$this->db->update();
$this->db->delete();
```

--------------------------------

### Get Global S3 Settings

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Retrieves the current global S3 sync configuration.

```APIDOC
## GET /api/v1/s3-credentials

### Description
Returns the current global S3 sync configuration that's shared across all repositories whose plugin config is set to "Use Global S3 Settings".

### Method
GET

### Endpoint
/api/v1/s3-credentials

### Parameters
#### Query Parameters
- **include_secrets** (integer) - Optional - If set to `1`, also returns `access_key` and `secret_key`. Requires a token with Display Secrets capability.

### Response
#### Success Response (200)
- **endpoint** (string) - The S3 service endpoint URL.
- **region** (string) - The AWS region for the S3 bucket.
- **bucket** (string) - The name of the S3 bucket.
- **path_prefix** (string) - An optional prefix for objects stored in the S3 bucket.
- **access_key** (string) - The S3 access key ID (only returned if `include_secrets=1`).
- **secret_key** (string) - The S3 secret access key (only returned if `include_secrets=1`).
- **configured** (boolean) - True if endpoint, bucket, and access_key are all populated.

### Response Example (without `include_secrets`)
```json
{
  "endpoint": "https://s3.us-west-1.amazonaws.com",
  "region": "us-west-1",
  "bucket": "bbs-offsite",
  "path_prefix": "",
  "configured": true
}
```

### Response Example (with `?include_secrets=1`)
```json
{
  "endpoint": "https://s3.us-west-1.amazonaws.com",
  "region": "us-west-1",
  "bucket": "bbs-offsite",
  "path_prefix": "",
  "access_key": "AKIA…",
  "secret_key": "…",
  "configured": true
}
```
```

--------------------------------

### Restore from Local Backup File

Source: https://github.com/marcpope/borgbackupserver/wiki/Server-Backup-and-Restore

Initiate the restore process from a local backup archive file. This command starts the interactive 7-step restore script.

```bash
sudo /var/www/bbs/bin/bbs-restore /tmp/bbs-backup-2026-03-04_120000.tar.gz
```

--------------------------------

### Get One User

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Retrieves details for a specific user by their ID.

```APIDOC
## Get One User

### Description
Retrieves details for a specific user by their ID. Returns the same shape as a single entry in the list users response.

### Method
GET

### Endpoint
/api/v1/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user.
```

--------------------------------

### Manage BorgBackupAgent Service

Source: https://github.com/marcpope/borgbackupserver/wiki/Windows-Agent-Setup

Commands to query, stop, start, and restart the Windows service, as well as view logs.

```powershell
# Check service status
sc query BorgBackupAgent

# Stop the agent
Stop-Service BorgBackupAgent

# Start the agent
Start-Service BorgBackupAgent

# Restart the agent
Restart-Service BorgBackupAgent

# View last 50 log lines
Get-Content "C:\ProgramData\bbs-agent\bbs-agent.log" -Tail 50

# Follow the log in real-time
Get-Content "C:\ProgramData\bbs-agent\bbs-agent.log" -Tail 50 -Wait
```

--------------------------------

### Display Recovery Codes

Source: https://github.com/marcpope/borgbackupserver/wiki/Two-Factor-Authentication

Example of the recovery codes generated upon successful 2FA setup. These codes must be stored securely as they are single-use.

```text
RECOVERY CODES (Save these in a safe place)

1. A3F9-2K7L-8M4N-P5Q6
2. B7C8-D9E1-F2G3-H4J5
3. K6L7-M8N9-P1Q2-R3S4
4. T5U6-V7W8-X9Y1-Z2A3
5. B4C5-D6E7-F8G9-H1J2
6. K3L4-M5N6-P7Q8-R9S1
7. T2U3-V4W5-X6Y7-Z8A9
8. B1C2-D3E4-F5G6-H7J8
9. K9L1-M2N3-P4Q5-R6S7
10. T8U9-V1W2-X3Y4-Z5A6
```

--------------------------------

### Get Client Detail

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Retrieves detailed information for a specific client, including associated repositories and plans.

```APIDOC
## GET /api/v1/clients/{id}

### Description
Retrieves detailed information for a specific client, identified by its ID. This includes client details, associated repositories, and backup plans.

### Method
GET

### Endpoint
/api/v1/clients/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the client to retrieve.
```

--------------------------------

### Get Storage Capacity

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Retrieves the provisioned, used, and free bytes for the default storage location.

```APIDOC
## GET /api/v1/storage/capacity

### Description
Provides the provisioned, used, and free bytes for the **default** storage location. This is useful for monitoring and capacity planning.

### Method
GET

### Endpoint
/api/v1/storage/capacity

### Response
#### Success Response (200)
- **provisioned_bytes** (integer) - The total provisioned storage space in bytes.
- **used_bytes** (integer) - The amount of storage space currently used in bytes.
- **free_bytes** (integer) - The amount of storage space available in bytes.

### Response Example
```json
{
  "provisioned_bytes": 10995116277760,
  "used_bytes": 4617089564672,
  "free_bytes": 6378026713088
}
```

### Errors
- 404 — no default storage location is configured
```

--------------------------------

### Get Plugin Schemas

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Fetch the schema definitions for each plugin type. This is useful for dynamically generating configuration forms.

```http
GET /api/v1/plugins/schema
```

--------------------------------

### Get Plugin Schemas

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Retrieves the field definitions for each plugin type, which can be used for building configuration forms programmatically.

```APIDOC
## GET /api/v1/plugins/schema

### Description
Retrieves the field definitions for each plugin type, which can be used for building configuration forms programmatically.

### Method
GET

### Endpoint
/api/v1/plugins/schema
```

--------------------------------

### Schedule Response Structure

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Example structure for a schedule entry returned by the List All Schedules API. Includes plan details, agent information, schedule settings, and run status.

```json
{
  "schedules": [
    {
      "plan_id": 5,
      "plan_name": "daily",
      "plan_enabled": true,
      "agent_id": 7,
      "agent_name": "web-01",
      "agent_status": "online",
      "repository_id": 12,
      "repository_name": "main",
      "frequency": "daily",
      "times": "02:00",
      "day_of_week": null,
      "day_of_month": null,
      "timezone": "America/New_York",
      "schedule_enabled": true,
      "next_run": "2026-05-28 02:00:00",
      "last_run": "2026-05-27 02:00:00",
      "last_status": "completed",
      "last_completed_at": "2026-05-27 02:04:32"
    }
  ]
}
```

--------------------------------

### Install Python 3 using Homebrew

Source: https://github.com/marcpope/borgbackupserver/wiki/macOS-Agent-Setup

Install Python 3 via Homebrew if the BBS Agent installer cannot locate it. This command ensures Python 3 is available in standard Homebrew paths.

```bash
brew install python3
```

--------------------------------

### List All Schedules API Endpoint

Source: https://github.com/marcpope/borgbackupserver/wiki/API

Get an aggregated view of all backup plans and their schedules, including the most recent status. This is useful for monitoring dashboards.

```http
GET /api/v1/schedules
```