Agent API Reference

Complete API documentation for the BackupAgent CLI agent.

Base URL: https://backupagent.ai

Authentication

All agent endpoints (except register) require an API key in the Authorization header:

Authorization: Bearer bak_your_api_key_here

API keys are generated during agent registration and shown once. They are stored as SHA-256 hashes on the server.

Quick Start

Install the agent:

curl -fsSL backupagent.ai/api/install | sh

backupagent register --token YOUR_TOKEN

Start the service:

sudo systemctl enable --now backupagent

Endpoints

POST/api/v1/agent/register

Auth: Registration token

Request Body

{
  "registrationToken": "string",
  "hostname": "string",
  "os": "linux",
  "arch": "amd64",
  "agentVersion": "1.0.0"
}

Response

{
  "agentId": "uuid",
  "apiKey": "bak_..."
}

POST/api/v1/agent/heartbeat

Send heartbeat with status and discovered databases

Auth: API Key

Request Body

{
  "status": "online",
  "agentVersion": "1.0.0",
  "configHash": "abc123",
  "discoveredDatabases": [{
    "dbType": "postgresql",
    "dbVersion": "16.2",
    "host": "localhost",
    "port": "5432",
    "databaseName": "myapp"
  }]
}

Response

{ "configChanged": true }

GET/api/v1/agent/config

Pull schedules, targets, and alert channels

Auth: API Key

Response

{
  "schedules": [...],
  "targets": [...],
  "alertChannels": [...]
}

POST/api/v1/agent/jobs/start

Start a new backup job

Auth: API Key

Request Body

{
  "databaseId": "uuid",
  "targetId": "uuid",
  "scheduleId": "uuid" // optional
}

Response

{ "jobId": "uuid" }

POST/api/v1/agent/jobs/{jobId}/status

Update job status at each pipeline stage

Auth: API Key

Request Body

{
  "status": "dumping|compressing|encrypting|uploading|completed|failed",
  "dumpSize": 1234567,
  "compressedSize": 456789,
  "uploadPath": "s3://bucket/path",
  "durationMs": 8500,
  "errorMessage": "string",
  "errorCode": "DUMP_FAIL"
}

Response

{ "success": true }

POST/api/v1/agent/jobs/{jobId}/verification

Submit restore verification results

Auth: API Key

Request Body

{
  "status": "passed|failed|error",
  "containerId": "docker-id",
  "restoreDurationMs": 3200,
  "checks": [{
    "checkType": "row_count|schema_match|custom_query",
    "checkName": "users table",
    "status": "passed|failed|skipped",
    "expectedValue": "1000",
    "actualValue": "1000",
    "deltaPct": 0.0
  }]
}

Response

{ "verificationId": "uuid" }

POST/api/v1/agent/jobs/{jobId}/logs

Upload batch of log entries (max 100)

Auth: API Key

Request Body

{
  "logs": [{
    "level": "info|warn|error",
    "message": "Starting backup...",
    "timestamp": "2026-04-09T02:00:01.000Z"
  }]
}

Response

{ "inserted": 5 }

POST/api/v1/agent/schema-snapshot

Submit database schema for drift detection

Auth: API Key

Request Body

{
  "databaseId": "uuid",
  "snapshot": { "tables": [...] },
  "tableCount": 15,
  "columnCount": 87
}

Response

{ "snapshotId": "uuid" }

POST/api/v1/agent/anomaly

Report a detected anomaly

Auth: API Key

Request Body

{
  "type": "size_anomaly|schema_drift|restore_failure",
  "severity": "info|warning|critical",
  "title": "Backup size 60% smaller than average",
  "description": "Expected ~2.4 GB, got 312 MB"
}

Response

{ "anomalyId": "uuid" }

Code Examples

curl

# Send heartbeat
curl -X POST https://backupagent.ai/api/v1/agent/heartbeat \
  -H "Authorization: Bearer bak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"online","agentVersion":"1.0.0"}'

Python

import requests

API_KEY = "bak_your_key"
BASE = "https://backupagent.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Send heartbeat
r = requests.post(f"{BASE}/api/v1/agent/heartbeat",
    json={"status": "online", "agentVersion": "1.0.0"},
    headers=headers)
print(r.json())

Go

client := api.NewClient("https://backupagent.ai", "bak_your_key")

resp, err := client.Heartbeat(api.HeartbeatRequest{
    Status:       "online",
    AgentVersion: "1.0.0",
})
fmt.Println(resp.ConfigChanged)