Custom Ingest API

Send backup results and custom notifications directly to BackupMonitor from your own scripts, scheduled tasks, or automation tools — no email required.

The Ingest API gives you two endpoints: one for structured backup job results and one for free-form notifications. This is useful for backup tools that don't send emails, pre/post backup scripts, infrastructure monitoring, or any event you want to surface in BackupMonitor.

Example use cases

  • Script-based backups (rsync, robocopy)
  • Disk space alerts
  • Database dump completions
  • Windows critical/error events
  • SSL / domain expiry checks
  • Service restart events
  • VM snapshot status
  • UPS / battery health
  • Failed automated deployments
  • DR test results

Authentication

Every request must include your API key in the X-Api-Key header. You can find your key in Settings → API inside the app.

Keep your API key secret. Anyone with the key can post data to your account. Do not commit it to version control or share it publicly. 

X-Api-Key: bm_your-api-key-here

Requests with a missing or invalid key return 401 Unauthorized. If you exceed the rate limit you will receive 429 Too Many Requests with a Retry-After header indicating when you can retry.

Endpoints

Post a Backup Entry

POST /api/ingest/backup

Records a backup job result in BackupMonitor's backup history. Use this when your script or backup tool finishes a job and you want the result to appear alongside your other backups.

Field Type Description
deviceName string required Name of the machine or device that ran the backup.
jobName string required Name of the backup job.
timestamp ISO 8601 required When the backup ran. Must include a UTC offset — e.g. 2024-06-04T14:00:00+02:00 or 2024-06-04T12:00:00Z.
status string required Result of the job. Recommended values: Success, Error, Warning.
message string required A short summary of the result.
sender string optional Source identifier for the script or tool posting the result, e.g. rsync-backup or script-server01. Together with deviceName and jobName, this value determines which device and job the entry is matched to - use a consistent sender so repeated posts update the same job rather than creating duplicates. Defaults to unknown@ingest if omitted.

Post a Notification

POST /api/ingest/notification

Sends a free-form notification event. Use this for anything beyond backup results - infrastructure alerts, health checks, script outcomes, or any event worth surfacing in BackupMonitor.

Field Type Description
deviceName string required Name of the machine or device the event originated from.
timestamp ISO 8601 required When the event occurred. Must include a UTC offset.
severity string required info | warning | error | critical
type string required A short identifier for the event category, e.g. disk_space_low, ssl_expiry. Used for filtering in the dashboard.
jobName string optional Name of a related job, if applicable.
message string optional Description of the event.
sender string optional Identifies the script or tool that sent the event, e.g. disk-monitor.

Code Examples

Report a Backup Job Result

Call this at the end of your backup script to record the result in BackupMonitor. 

API_KEY="bm_your-api-key-here"
DEVICE=$(hostname)
JOBNAME="Nightly Full Backup"
JOBSTATUS="Success"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")
MESSAGE="Backup completed. 142 GB transferred."

curl -i -X POST "https://ingest.backupmonitor.io/api/ingest/backup" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "deviceName": "'"$DEVICE"'",
    "jobName": "'"$JOBNAME"'",
    "timestamp": "'"$TIMESTAMP"'",
    "status": "'"$JOBSTATUS"'",
    "message": "'"$MESSAGE"'",
    "sender": "'"script-$DEVICE"'"
  }'

Post a Notification

Send a custom notification event from your script-— for alerts, health checks, or any event you want to surface in BackupMonitor. 

API_KEY="bm_your-api-key-here"
DEVICE=$(hostname)
JOBNAME="Job"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")
MESSAGE="This is a test."
SEVERITY="info"
TYPE="some_alert"

curl -i -X POST "https://ingest.backupmonitor.io/api/ingest/notification" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "deviceName": "'"$DEVICE"'",
    "jobName": "'"$JOBNAME"'",
    "timestamp": "'"$TIMESTAMP"'",
    "message": "'"$MESSAGE"'",
    "sender": "'"script-$DEVICE"'",
    "severity": "'"$SEVERITY"'",
    "type": "'"$TYPE"'"
  }'

Disk Space Alert

Run as a scheduled task (e.g. every hour). Posts a warning when free space drops below 20% and an error below 10%. Nothing is posted when disk space is healthy. 

#!/usr/bin/env bash

API_KEY="bm_your-api-key-here"
HOSTNAME=$(hostname)
WARNING_THRESHOLD=20  # % free
ERROR_THRESHOLD=10    # % free

OS="$(uname -s)"

get_mounts() {
  case "$OS" in
    Darwin)
      # Only the root APFS volume and /System/Volumes/Data represent real user space.
      # Skip simulator volumes and other APFS containers.
      df -P | awk 'NR>1' | grep -E "^/dev/" | grep -vE "CoreSimulator|Preboot|Update|xarts|iSCPreboot|Hardware|/VM$"
      ;;
    Linux)
      df -P | awk 'NR>1' | grep -E "^/dev/"
      ;;
    *)
      df -P | awk 'NR>1' | grep -E "^/dev/"
      ;;
  esac
}

get_mounts | while read -r filesystem size used avail pct mount; do
   used_pct=${pct%%%}
   free_pct=$((100 - used_pct))

    if [ "$free_pct" -le "$ERROR_THRESHOLD" ]; then
        severity="error"
    elif [ "$free_pct" -le "$WARNING_THRESHOLD" ]; then
        severity="warning"
    else
        echo "[ok] $mount ($filesystem): ${free_pct}% free — skipping"
        continue
    fi

    curl -X POST "https://ingest.backupmonitor.io/api/ingest/notification" \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: $API_KEY" \
      -d '{
        "deviceName": "'"$HOSTNAME"'",
        "timestamp": "'"$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")"'",
        "message": "'"Drive $mount ($filesystem) has only ${free_pct}% free space remaining."'",
        "sender": "'"disk-monitor"'",
        "severity": "'"$severity"'",
        "type": "'"disk_space_low"'"
      }'
    echo "[$severity] $mount ($filesystem): ${free_pct}% free — notification sent"
done