BackupX/docs-site/docs/reference/api.md

sidebar_position, title, description

sidebar_position	title	description
1	API Reference	BackupX REST endpoints, authentication methods, role boundaries, streaming responses, and public probes.

API Reference

The interactive API is rooted at /api. Most endpoints accept either a user JWT or an API key; Agent protocol endpoints use a node-specific token. Public probes and one-time installers are listed separately.

Authentication

User JWT

Obtain a JWT through POST /api/auth/login and send it as a Bearer token:

curl -H "Authorization: Bearer $BACKUPX_TOKEN" \
  https://backup.example.com/api/backup/tasks

The login flow may require OTP, TOTP, recovery code, a trusted-device token, or WebAuthn depending on account and system settings.

API key

An administrator creates API keys in the console or through POST /api/api-keys. The plaintext bax_... value is returned only once.

curl -H "X-Api-Key: $BACKUPX_API_KEY" \
  https://backup.example.com/api/dashboard/stats

Authorization: Bearer bax_... is also accepted. API keys carry an admin, operator, or viewer role and can be disabled or given an expiry.

Agent token

Agent protocol handlers authenticate the node token supplied in X-Agent-Token. This token is not a user credential and must not be used with the interactive resource API.

Access labels

The tables use these labels:

Label	Required access
Public	No JWT or API key; an install route still requires its one-time token
Auth	Any authenticated viewer, operator, or admin
Operator	operator or admin
Admin	admin only
Agent	Valid node-specific Agent token

Viewers can use read endpoints except node filesystem browsing. Operators can run and mutate backup resources. Administrators additionally manage users, API keys, settings, nodes, install tokens, and node-token rotation. A rejected role returns HTTP 403.

Authentication and account security

Method	Endpoint	Access	Description
GET	/api/auth/setup/status	Public	Check whether first-admin setup is required
POST	/api/auth/setup	Public	Create the first administrator when no user exists
POST	/api/auth/login	Public	Complete password or MFA login and obtain a JWT
POST	/api/auth/otp/send	Public	Send a configured login OTP
POST	/api/auth/webauthn/login/options	Public	Begin passkey login
POST	/api/auth/logout	Auth	Acknowledge logout; the client must discard its stateless JWT
GET	/api/auth/profile	Auth	Read the current account
PUT	/api/auth/password	Auth	Change the current account password
POST	/api/auth/2fa/setup	Auth	Prepare TOTP enrollment
POST	/api/auth/2fa/enable	Auth	Enable TOTP after verification
POST	/api/auth/2fa/recovery-codes	Auth	Regenerate recovery codes
DELETE	/api/auth/2fa	Auth	Disable TOTP
PUT	/api/auth/otp/config	Auth	Update OTP login configuration
POST	/api/auth/webauthn/register/options	Auth	Begin passkey registration
POST	/api/auth/webauthn/register/finish	Auth	Finish passkey registration
GET	/api/auth/webauthn/credentials	Auth	List passkeys
DELETE	/api/auth/webauthn/credentials/:id	Auth	Delete a passkey
GET	/api/auth/trusted-devices	Auth	List trusted devices
DELETE	/api/auth/trusted-devices/:id	Auth	Revoke a trusted device

Use an interactive JWT, not an automation API key, for account-security endpoints.

System and storage targets

Method	Endpoint	Access	Description
GET	/api/system/info	Auth	Version and system information
GET	/api/system/update-check	Auth	Check available releases
GET	/api/storage-targets	Auth	List storage targets
POST	/api/storage-targets	Operator	Create a target
POST	/api/storage-targets/test	Operator	Test an unsaved configuration
GET	/api/storage-targets/rclone/backends	Auth	List available rclone backends
POST	/api/storage-targets/google-drive/auth-url	Operator	Start Google Drive authorization
POST	/api/storage-targets/google-drive/complete	Operator	Complete Google Drive authorization
GET	/api/storage-targets/google-drive/callback	Auth	Handle the OAuth callback
GET	/api/storage-targets/:id	Auth	Read a target
PUT	/api/storage-targets/:id	Operator	Update a target
DELETE	/api/storage-targets/:id	Operator	Delete a target
PUT	/api/storage-targets/:id/star	Operator	Toggle favorite state
POST	/api/storage-targets/:id/test	Operator	Test a saved target
GET	/api/storage-targets/:id/usage	Auth	Read recorded usage
GET	/api/storage-targets/:id/google-drive/profile	Auth	Read the connected Google Drive profile

Backup tasks

Method	Endpoint	Access	Description
GET	/api/backup/tasks	Auth	List tasks
GET	/api/backup/tasks/tags	Auth	List task tags
GET	/api/backup/tasks/export	Auth	Download all task definitions, or select them with ?ids=1,2
POST	/api/backup/tasks/import	Operator	Import task definitions, up to 1 MiB
POST	/api/backup/tasks/batch/toggle	Operator	Enable or disable tasks in bulk
POST	/api/backup/tasks/batch/delete	Operator	Delete tasks in bulk
POST	/api/backup/tasks/batch/run	Operator	Run tasks in bulk
GET	/api/backup/tasks/:id	Auth	Read a task
POST	/api/backup/tasks	Operator	Create a task
PUT	/api/backup/tasks/:id	Operator	Update a task
DELETE	/api/backup/tasks/:id	Operator	Delete a task
PUT	/api/backup/tasks/:id/toggle	Operator	Enable or disable a task
POST	/api/backup/tasks/:id/run	Operator	Trigger a backup
POST	/api/backup/tasks/:id/verify	Operator	Trigger verification from a task

Task export intentionally excludes database passwords and storage credentials. It is useful for migration and review, not a complete control-plane backup.

Backup and restore records

Method	Endpoint	Access	Description
GET	/api/backup/records	Auth	List and filter backup records
POST	/api/backup/records/batch-delete	Operator	Delete records in bulk
GET	/api/backup/records/:id	Auth	Read a backup record
GET	/api/backup/records/:id/logs/stream	Auth	Stream logs with server-sent events
GET	/api/backup/records/:id/download	Auth	Download an artifact
GET	/api/backup/records/:id/contents	Auth	Browse artifact contents where supported
POST	/api/backup/records/:id/restore	Operator	Start a restore
POST	/api/backup/records/:id/replicate	Operator	Replicate an existing artifact
POST	/api/backup/records/:id/verify	Operator	Verify an existing artifact
PUT	/api/backup/records/:id/lock	Operator	Set retention lock state
DELETE	/api/backup/records/:id	Operator	Delete a record and its managed artifact
GET	/api/restore/records	Auth	List restore records
GET	/api/restore/records/:id	Auth	Read a restore record
GET	/api/restore/records/:id/logs/stream	Auth	Stream restore logs
GET	/api/replication/records	Auth	List replication records
GET	/api/replication/records/:id	Auth	Read a replication record
GET	/api/verify/records	Auth	List verification records
GET	/api/verify/records/:id	Auth	Read a verification record
GET	/api/verify/records/:id/logs/stream	Auth	Stream verification logs

Templates, reports, and dashboard

Method	Endpoint	Access	Description
GET	/api/task-templates	Auth	List task templates
GET	/api/task-templates/:id	Auth	Read a task template
POST	/api/task-templates	Operator	Create a template
PUT	/api/task-templates/:id	Operator	Update a template
DELETE	/api/task-templates/:id	Operator	Delete a template
POST	/api/task-templates/:id/apply	Operator	Create tasks from a template
GET	/api/reports/compliance	Auth	Read compliance evidence
GET	/api/reports/compliance/export	Auth	Export compliance evidence as CSV
GET	/api/dashboard/stats	Auth	Summary statistics
GET	/api/dashboard/timeline	Auth	Recent activity
GET	/api/dashboard/sla	Auth	RPO and SLA status
GET	/api/dashboard/cluster	Auth	Cluster summary
GET	/api/dashboard/breakdown	Auth	Task and record breakdown
GET	/api/dashboard/node-performance	Auth	Per-node performance

Notifications, settings, and administration

Method	Endpoint	Access	Description
GET	/api/notifications	Auth	List notification channels
GET	/api/notifications/:id	Auth	Read a channel
POST	/api/notifications	Operator	Create a channel
PUT	/api/notifications/:id	Operator	Update a channel
DELETE	/api/notifications/:id	Operator	Delete a channel
POST	/api/notifications/test	Operator	Test an unsaved configuration
POST	/api/notifications/:id/test	Operator	Test a saved channel
GET	/api/settings	Auth	Read system settings
PUT	/api/settings	Admin	Update system settings
GET	/api/users	Admin	List users
POST	/api/users	Admin	Create a user
PUT	/api/users/:id	Admin	Update a user
POST	/api/users/:id/2fa/reset	Admin	Reset a user's second factor
DELETE	/api/users/:id	Admin	Delete a user
GET	/api/api-keys	Admin	List API keys without plaintext values
POST	/api/api-keys	Admin	Create an API key and return its plaintext once
PUT	/api/api-keys/:id/toggle	Admin	Enable or disable an API key
DELETE	/api/api-keys/:id	Admin	Revoke an API key

Audit, events, search, and discovery

Method	Endpoint	Access	Description
GET	/api/audit-logs	Auth	List and filter audit records
GET	/api/audit-logs/export	Auth	Export audit records
GET	/api/events/stream	Auth	Stream real-time application events with SSE
GET	/api/search	Auth	Search supported resources
POST	/api/database/discover	Auth	Discover databases from supplied connection details

Nodes

Method	Endpoint	Access	Description
GET	/api/nodes	Auth	List nodes
GET	/api/nodes/:id	Auth	Read a node
GET	/api/nodes/:id/fs/list	Operator	Browse the selected node filesystem
POST	/api/nodes	Admin	Create a node
POST	/api/nodes/batch	Admin	Create up to 50 nodes
PUT	/api/nodes/:id	Admin	Update a node
DELETE	/api/nodes/:id	Admin	Delete an unreferenced node
POST	/api/nodes/:id/install-tokens	Admin	Create a one-time installer
GET	/api/nodes/:id/install-script-preview	Admin	Preview generated install material
POST	/api/nodes/:id/rotate-token	Admin	Rotate the long-lived node token

Agent protocol

These routes are for the backupx agent process and authenticate inside the handler with the node token.

Method	Endpoint	Access	Description
POST	/api/agent/heartbeat	Agent	Report liveness and node state
POST	/api/agent/commands/poll	Agent	Claim a pending command
POST	/api/agent/commands/:id/result	Agent	Report a command result
GET	/api/agent/tasks/:id	Agent	Fetch a runnable task specification
POST	/api/agent/records/:id	Agent	Append logs or update backup state
PUT	/api/agent/records/:id/artifacts/:targetId	Agent	Stream a relayed artifact to the Master
GET	/api/agent/restores/:id/spec	Agent	Fetch restore instructions
GET	/api/agent/restores/:id/artifact	Agent	Stream a restore artifact
POST	/api/agent/restores/:id	Agent	Update restore state
GET	/api/v1/agent/self	Agent	Validate node identity during installation

Public operational and install routes

Method	Endpoint	Access	Description
GET	/health	Public	Liveness
GET	/api/health	Public	API-prefixed liveness alias
GET	/ready	Public	SQLite readiness
GET	/api/ready	Public	API-prefixed readiness alias
GET	/metrics	Public	Prometheus metrics
GET	/install/:token	Public	Consume a one-time Agent installer token
GET	/api/install/:token	Public	API-prefixed installer route
GET	/install/:token/compose.yml	Public	Render a Docker Agent Compose file
GET	/api/install/:token/compose.yml	Public	API-prefixed Docker Compose route

Restrict probes and metrics to monitoring networks. Install tokens are single-use, time-limited secrets and must not be written to public logs.

Response formats

Most JSON successes use:

{
  "code": "OK",
  "message": "success",
  "data": {}
}

Errors use an HTTP 4xx or 5xx status plus a stable application code:

{
  "code": "BACKUP_TASK_NOT_FOUND",
  "message": "备份任务不存在"
}

Clients should branch on the HTTP status and code, not the localized message.

Artifact downloads, task JSON export, audit or compliance exports, installer responses, and /metrics return their native content types instead of the JSON envelope. Log and event streams use text/event-stream; reverse proxies must keep response buffering disabled.