Start full backup

StartFullBackup¶

StartFullBackup

Alias: StartBackupServer

Description: Starts a backup run manually and returns the created run record.

By default, this command starts a full backup across all registered participants. Pass participants to create a scoped module backup, for example only the trades participant. Scoped backups are useful as pre-change snapshots and for module-scoped restore workflows, but they are not full disaster restore points.

The current handler is synchronous: it returns after the backup run finishes or fails. A successful response can contain status completed or partial; status failed returns an error response. Only completed runs can be used as restore sources.

For long-running backups, use GetBackupProgress or subscribe to the backup.progress stream from another client session while StartFullBackup is executing.

Access Control¶

SESSION_ADMIN, SESSION_MANAGER

Request Parameters¶

Field	Type	Required	Description
`participants`	array	No	Optional participant names for scoped backup, for example `["trades"]`. Omit to run a full backup.

Request Example¶

{
  "command": "StartFullBackup",
  "extID": "1",
  "data": {
    "participants": ["trades"]
  }
}

Response Data¶

Returns a flat backup run object. See GetBackupRun for the full field list.

Response Example¶

{
  "run_id": "20260629-121045-000001",
  "type": "scoped",
  "trigger": "manual",
  "status": "completed",
  "path": "backups/completed/20260629-121045-000001",
  "started_at": 1782727845,
  "finished_at": 1782727852,
  "error_summary": "",
  "requested_participants": ["trades"],
  "participants": [
    {
      "name": "trades",
      "critical": true,
      "ok": true,
      "status": "completed",
      "started_at": 1782727845,
      "finished_at": 1782727846,
      "error": "",
      "artifacts": [
        {
          "logical_name": "trades.db",
          "path": "backups/completed/20260629-121045-000001/trades.db",
          "size_bytes": 327680,
          "sha256": "f2a1...",
          "integrity_ok": true,
          "integrity_error": "",
          "validation_ok": true,
          "validation_error": ""
        }
      ]
    }
  ]
}

Errors¶

HTTP Code	Description
`400`	`participants` is not an array, contains invalid names, or requested participants are not registered
`409`	Backup run is already in progress
`500`	Backup run failed