dockbare / api

general

Everything the UI does is plain HTTP underneath, so you can drive dockbare from CI, cron, or your own scripts.

base url: All endpoints are relative to the app's host and port, e.g. http://localhost:5000.
content-type: Requests with a body use application/json, unless noted (e.g. file uploads).
responses: JSON, unless a file download is indicated.

state & overview

GET/api/state

Aggregate snapshot of volumes, backups, schedules, sync status, settings, logs, and overview.

200 OK

{
  "volumes": [
    { "name": "my_volume_1", "container": ["container_id", "container_name"] }
  ],
  "backups_structured": {
    "my_volume_1": [
      {
        "filename": "2025-08-29_22-10-00.tar.gz",
        "size": 1234567,
        "size_formatted": "1.2 MB",
        "path": "/backups/my_volume_1/2025-08-29_22-10-00.tar.gz",
        "timestamp": "2025-08-29T22:10:00Z",
        "ftp_status": "synced",
        "download_url": "/api/backups/download?path=..."
      }
    ]
  },
  "schedules": [
    {
      "volume": "my_volume_1",
      "enabled": true,
      "interval_str": "6h",
      "next_run": "2025-08-30T04:10:00Z",
      "ftp_upload_enabled": true,
      "prune_keep_days": 30
    }
  ],
  "sync_status": { "enabled": true, "interval_minutes": 60, "next_run": "..." },
  "ftp_settings": { "...": "FTP config, password omitted" },
  "notification_settings": { "...": "ntfy config" },
  "log_settings": { "max_lines": 200, "timezone": "system" },
  "logs": ["[2025-08-29T22:13:00Z] Log message..."],
  "overview": {
    "backed_up_volumes_count": 1,
    "total_volumes_count": 1,
    "next_scheduled_backup": "2025-08-30T04:10:00Z",
    "currently_running_backups": []
  }
}

GET/api/storage_prediction

Current total backup size and predicted size over 30 days, based on active schedules.

200 OK

{ "current_size_bytes": 123456789, "predicted_size_bytes_30d": 234567890 }

backups & restore

POST/api/backup

Start a backup for a volume as an async task.

request

{ "volume": "my_volume_name", "upload_to_ftp": true // optional }

200 OK

{ "message": "Backup started...", "task_id": "unique-task-id" }

POST/api/restore

Restore a volume from a backup file as an async task.

request

{ "volume": "target_volume", "backup_path": "/backups/source/file.tar.gz" }

200 OK

{ "message": "Restore started...", "task_id": "unique-task-id" }

POST/api/upload_backup

Upload a .tar.gz backup file into a volume's backup directory. Sent as multipart/form-data with fields volume (string) and backup_file (file).

200 OK

{ "message": "Upload successful." }

POST/api/prune_extended

Delete backups for a volume older than the given retention window.

request

{ "volume": "my_volume_name", "days": 30, "hours": 0, "minutes": 0 }

200 OK

{ "deleted_count": 5 }

GET/api/backups/download?path=<file_path>

Download a .tar.gz backup. Returns the raw file with Content-Disposition: attachment.

DELETE/api/backups/<volume>/<filename.tar.gz>

Delete a single backup file.

200 OK

{ "message": "Backup deleted" }

schedules

POST/api/schedules

Add or overwrite a backup schedule for a volume.

request

{ "volume": "my_volume_name", "interval_days": 1 // + optional interval / prune / notification fields }

200 OK

{ "message": "Schedule added" }

PUT/api/schedules/<volume>

Update an existing schedule. Same body as add, without volume.

200 OK

{ "message": "Schedule updated" }

DELETE/api/schedules/<volume>

Remove a schedule and its job.

200 OK

{ "message": "Schedule removed" }

POST/api/schedules/toggle

Pause or resume a schedule.

request

{ "volume": "my_volume_name", "enabled": false }

200 OK

{ "message": "Schedule for my_volume_name updated" }

settings & logs

POST/api/sync_now

Start a full FTP sync as an async task.

200 OK

{ "message": "FTP sync started.", "task_id": "unique-task-id" }

POST/api/settings/ftp

Save FTP settings and reschedule the periodic sync job.

request

{ "host": "ftp.example.com" // + all FTP fields }

200 OK

{ "message": "FTP settings saved" }

POST/api/settings/notifications

Save ntfy notification settings.

request

{ "base_url": "https://ntfy.sh", "topic": "my-backups" }

200 OK

{ "message": "Notification settings saved" }

POST/api/settings/logs

Save the in-memory log line cap and UI timezone preference.

request

{ "max_lines": 500, "timezone": "Europe/Berlin" }

200 OK

{ "message": "Log settings saved" }

GET/api/backups/logs?path=<file_path>

Log lines associated with a specific backup file.

200 OK

["[2025-08-30T00:19:00Z] log line...", "..."]

GET/api/logs/download

Download current in-memory logs as a text file (Content-Disposition: attachment).

async tasks

GET/api/task_status/<task_id>

Status of an async task (backup, restore, sync).

200 OK

// while running
{ "status": "running", "message": "..." }

// on completion (success or failure)
{ "status": "success", "message": "..." }