package v1
Get desktop application:
View/edit binary Protocol Buffers messages
rpc HashPassword (, )
authentication.proto:14rpc Login (, )
authentication.proto:13message
authentication.proto:17string username = 1
string password = 2
message
authentication.proto:22string token = 1
JWT token
service Backrest
service.proto:19rpc AddRepo (, )
service.proto:28message
service.proto:114optional repo = 1
rpc Backup (, )
service.proto:41Backup schedules a backup operation. It accepts a plan id and returns empty if the task is enqueued.
message
service.proto:14string value = 1
plan_id - named 'value' for curl script backwards compatibility
bool dry_run = 2
optional, simulate backup without creating snapshot
rpc Cancel (, )
service.proto:53Cancel attempts to cancel a task with the given operation ID. Not guaranteed to succeed.
rpc CheckRepoExists (, )
service.proto:26message
service.proto:104optional repo = 1
message
service.proto:108bool exists = 1
string error = 2
bool host_key_untrusted = 5
rpc ClearHistory (, )
service.proto:65Clears the history of operations
message
service.proto:132optional selector = 1
bool only_failed = 2
rpc DoRepoTask (, )
service.proto:44DoRepoTask schedules a repo task. It accepts a repo id and a task type and returns empty if the task is enqueued.
message
service.proto:118string repo_id = 1
DoRepoTaskRequest.Task task = 2
rpc Forget (, )
service.proto:47Forget schedules a forget operation. It accepts a plan id and returns empty if the task is enqueued.
message
service.proto:137string repo_id = 1
string plan_id = 2
string snapshot_id = 3
rpc GeneratePairingToken (, )
service.proto:75GeneratePairingToken creates a new pairing token on the server that can be shared with clients to simplify peering. The token format is "<keyid>:<secret>#<instanceid>" — an opaque string the client pastes when adding a known host.
message
service.proto:231string label = 1
human-readable label for the token
int64 ttl_seconds = 2
time-to-live in seconds (e.g. 3600 for 1 hour)
int32 max_uses = 3
max number of clients that can pair with this token, 0 for unlimited
repeated permissions = 4
permissions to grant to clients that pair with this token
message
service.proto:238string token = 1
the opaque pairing token string: "<keyid>:<secret>#<instanceid>"
rpc GetConfig (, )
service.proto:20rpc GetDownloadURL (, )
service.proto:62GetDownloadURL returns a signed download URL given an operation ID and file path.
message
service.proto:176int64 op_id = 1
string file_path = 2
rpc GetLogs (, stream )
service.proto:56GetLogs returns the keyed large data for the given operation.
message
service.proto:172string ref = 1
rpc GetOperationEvents (, stream )
service.proto:32rpc GetOperations (, )
service.proto:34message
service.proto:148optional selector = 1
int64 last_n = 2
limit to the last n operations
rpc GetSummaryDashboard (, )
service.proto:71GetSummaryDashboard returns data for the dashboard view.
message
service.proto:199repeated repo_summaries = 1
repeated plan_summaries = 2
string config_path = 10
string data_path = 11
rpc ListSnapshotFiles (, )
service.proto:38message
service.proto:161string repo_guid = 1
string snapshot_id = 2
string path = 3
message
service.proto:167string path = 1
repeated entries = 2
rpc ListSnapshots (, )
service.proto:36message
service.proto:143string repo_id = 1
string plan_id = 2
message
restic.proto:36ResticSnapshotList represents a list of restic snapshots.
repeated snapshots = 1
rpc PathAutocomplete (, )
service.proto:68PathAutocomplete provides path autocompletion options for a given filesystem path.
rpc RemoveRepo (, )
service.proto:30rpc Restore (, )
service.proto:50Restore schedules a restore operation.
message
service.proto:153string plan_id = 1
string repo_id = 5
string snapshot_id = 2
string path = 3
string target = 4
rpc RunCommand (, )
service.proto:59RunCommand executes a generic restic command on the repository.
message
service.proto:194string repo_id = 1
string command = 2
rpc SetConfig (, )
service.proto:22rpc SetupSftp (, )
service.proto:24message
service.proto:90string host = 1
string port = 2
string username = 3
optional string password = 4
If not provided, we only generate the key and add host to known_hosts
message
service.proto:97string public_key = 1
string key_path = 2
string known_hosts_path = 3
string error = 4
message
config.proto:306Used in:
bool disabled = 1
disable authentication.
repeated users = 2
users to allow access to the UI.
message
restic.proto:41BackupProgressEntriy represents a single entry in the backup progress stream.
Used in:
oneof entry
status = 1
summary = 2
message
restic.proto:77Used in:
string item = 1
See https://restic.readthedocs.io/en/stable/075_scripting.html#error
string during = 2
string message = 3
message
restic.proto:49BackupProgressStatusEntry represents a single status entry in the backup progress stream.
Used in:
double percent_done = 1
See https://restic.readthedocs.io/en/stable/075_scripting.html#id1
0.0 - 1.0
int64 total_files = 2
int64 total_bytes = 3
int64 files_done = 4
int64 bytes_done = 5
repeated string current_file = 6
message
restic.proto:60BackupProgressSummary represents a the summary event emitted at the end of a backup stream.
Used in:
int64 files_new = 1
See https://restic.readthedocs.io/en/stable/075_scripting.html#summary
int64 files_changed = 2
int64 files_unmodified = 3
int64 dirs_new = 4
int64 dirs_changed = 5
int64 dirs_unmodified = 6
int64 data_blobs = 7
int64 tree_blobs = 8
int64 data_added = 9
int64 total_files_processed = 10
int64 total_bytes_processed = 11
double total_duration = 12
string snapshot_id = 13
message
config.proto:179Used in:
optional schedule = 1
oneof mode
bool structure_only = 100
only check the structure of the repo. No pack data is read.
double read_data_subset_percent = 101
check a percentage of pack data.
message
config.proto:133Used in:
CommandPrefix.IONiceLevel io_nice = 1
ionice level to set.
CommandPrefix.CPUNiceLevel cpu_nice = 2
nice level to set.
Used in:
CPU_DEFAULT = 0
CPU_HIGH = 1
CPU_LOW = 2
Used in:
IO_DEFAULT = 0
IO_BEST_EFFORT_LOW = 1
IO_BEST_EFFORT_HIGH = 2
IO_IDLE = 3
message
config.proto:12Config is the top level config object for restic UI.
Used as request type in: Backrest.SetConfig
Used as response type in: Backrest.AddRepo, Backrest.GetConfig, Backrest.RemoveRepo, Backrest.SetConfig
int32 modno = 1
modification number, used for read-modify-write consistency in the UI. Incremented on every write.
int32 version = 6
version of the config file format. Used to determine when to run migrations.
string instance = 2
The instance name for the Backrest installation. This identifies backups created by this instance and is displayed in the UI.
repeated repos = 3
repeated plans = 4
optional auth = 5
optional multihost = 7
Used in:
TASK_NONE = 0
TASK_INDEX_SNAPSHOTS = 1
TASK_PRUNE = 2
TASK_CHECK = 3
TASK_STATS = 4
TASK_UNLOCK = 5
TASK_FORGET = 6
message
config.proto:168Used in:
optional schedule = 1
optional retention = 2
message
config.proto:206Used in: ,
repeated Hook.Condition conditions = 1
Hook.OnError on_error = 2
oneof action
action_command = 100
action_webhook = 101
action_discord = 102
action_gotify = 103
action_slack = 104
action_shoutrrr = 105
action_healthchecks = 106
action_telegram = 107
message
config.proto:256Used in:
string command = 1
Used in: ,
CONDITION_UNKNOWN = 0
CONDITION_ANY_ERROR = 1
error running any operation.
CONDITION_SNAPSHOT_START = 2
backup started.
CONDITION_SNAPSHOT_END = 3
backup completed (success or fail).
CONDITION_SNAPSHOT_ERROR = 4
snapshot failed.
CONDITION_SNAPSHOT_WARNING = 5
snapshot completed with warnings.
CONDITION_SNAPSHOT_SUCCESS = 6
snapshot succeeded.
CONDITION_SNAPSHOT_SKIPPED = 7
snapshot was skipped e.g. due to no changes.
CONDITION_PRUNE_START = 100
prune conditions
prune started.
CONDITION_PRUNE_ERROR = 101
prune failed.
CONDITION_PRUNE_SUCCESS = 102
prune succeeded.
CONDITION_CHECK_START = 200
check conditions
check started.
CONDITION_CHECK_ERROR = 201
check failed.
CONDITION_CHECK_SUCCESS = 202
check succeeded.
CONDITION_FORGET_START = 300
forget conditions
forget started.
CONDITION_FORGET_ERROR = 301
forget failed.
CONDITION_FORGET_SUCCESS = 302
forget succeeded.
message
config.proto:271Used in:
string webhook_url = 1
string template = 2
template for the webhook payload.
message
config.proto:276Used in:
string base_url = 1
string token = 3
string template = 100
template for the webhook payload.
string title_template = 101
template for the webhook title.
int32 priority = 102
priority level for the notification (1-10)
message
config.proto:294Used in:
string webhook_url = 1
string template = 2
Used in:
ON_ERROR_IGNORE = 0
ON_ERROR_CANCEL = 1
cancels the operation and skips subsequent hooks
ON_ERROR_FATAL = 2
fails the operation and subsequent hooks.
ON_ERROR_RETRY_1MINUTE = 100
retry the operation every minute
ON_ERROR_RETRY_10MINUTES = 101
retry the operation every 10 minutes
ON_ERROR_RETRY_EXPONENTIAL_BACKOFF = 103
retry the operation with exponential backoff up to 1h max.
message
config.proto:289Used in:
string shoutrrr_url = 1
string template = 2
message
config.proto:284Used in:
string webhook_url = 1
string template = 2
template for the webhook payload.
message
config.proto:299Used in:
string bot_token = 1
string chat_id = 2
string template = 3
template for the message text.
message
config.proto:260Used in:
string webhook_url = 1
Webhook.Method method = 2
string template = 100
Used in:
UNKNOWN = 0
GET = 1
POST = 2
message
service.proto:181Used in:
string name = 1
string type = 2
string path = 3
int64 uid = 4
int64 gid = 5
int64 size = 6
int64 mode = 7
string mtime = 8
string atime = 9
string ctime = 10
message
config.proto:27Used in:
optional identity = 1
repeated known_hosts = 2
repeated authorized_clients = 3
repeated pairing_tokens = 4
active pairing tokens generated by this instance (server-side only)
message
config.proto:44Used in:
string secret = 1
the one-time secret used to validate the pairing request
string label = 2
human-readable label for this token
int64 created_at_unix = 3
unix timestamp when the token was created
int64 expires_at_unix = 4
unix timestamp when the token expires
int32 max_uses = 5
maximum number of clients that can pair with this token, 0 means unlimited
int32 uses = 6
number of times this token has been used
repeated permissions = 7
permissions granted to clients that pair with this token
message
config.proto:33Used in:
string instance_id = 1
a human readable name for the peer, typically the same as its instance ID.
string keyid = 2
the key ID of the peer. This must match the sha256 of the public key the client provides in handshake.
repeated permissions = 5
permissions granted to this peer.
string instance_url = 4
Known host only fields
instance URL, required for a known host. Otherwise meaningless.
string initial_pairing_secret = 6
one-time pairing secret sent during first handshake to auto-authorize with the server. Cleared after successful pairing.
message
config.proto:54Used in: , ,
Permission.Type type = 1
Scopes are any of '*', 'repo:<repo_id>' or 'plan:<plan_id>','-repo:<repo_id>','-plan:<plan_id>'. '*' means all repos and plans, 'repo:<repo_id>' means the repo with the given ID, 'plan:<plan_id>' means the plan with the given ID. '!repo:<repo_id>' means all repos except the one with the given ID, '!plan:<plan_id>' means all plans except the one with the given ID.
repeated string scopes = 2
Used in:
PERMISSION_UNKNOWN = 0
PERMISSION_READ_OPERATIONS = 1
Granted on a knownHost (by client → host): the local instance pushes operations for in-scope repos/plans up to that known host, and exposes those resource IDs/GUIDs in the resource list it sends. Granted on an authorizedClient: no effect. The host never pushes operations down to clients.
PERMISSION_READ_CONFIG = 2
Granted on an authorizedClient (by host → client): in-scope repos/plans are included in the host's RemoteConfig and resource list sent to the client (read-only view of host config). Granted on a knownHost (by client → host): in-scope repos/plans are included in the client's RemoteConfig and resource list sent to the host (read-only view of client config).
PERMISSION_READ_WRITE_CONFIG = 3
Granted on an authorizedClient (by host → client): same view as READ_CONFIG. There is no client→host SetConfig path, so the "write" half is currently a no-op on the host side. Granted on a knownHost (by client → host): everything READ_CONFIG does, plus the client accepts SetConfig from the host for in-scope IDs (create/update/delete plans, create/update/delete repos).
PERMISSION_RECEIVE_SHARED_REPOS = 4
Both peers must grant this for shared repos to flow: - Granted on an authorizedClient (by host → client): host pushes in-scope repos marked as 'shared' to that client via SetConfig. A scopeless grant acts as a wildcard (push every shared repo); a scoped grant restricts which shared repos are pushed. - Granted on a knownHost (by client → host): client accepts pushed shared repos that are new or already owned by this host. Always evaluated scope-lessly on the client — scopes are ignored here because the client doesn't pre-know the incoming repo IDs. If either side is missing the grant, no shared repos are transferred.
message
service.proto:79OpSelector is a message that can be used to select operations e.g. by query.
Used in: ,
repeated int64 ids = 1
optional string instance_id = 6
optional string original_instance_keyid = 8
optional string repo_guid = 7
optional string plan_id = 3
optional string snapshot_id = 4
optional int64 flow_id = 5
optional int64 modno_gte = 9
message
operations.proto:16Operation is the basic unit of record in backrest
Used in:
int64 id = 1
required, primary ID of the operation. ID is sequential based on creation time of the operation.
int64 original_id = 13
int64 modno = 12
modno increments with each change to the operation. This supports easy diffing.
int64 flow_id = 10
flow id groups operations together, e.g. by an execution of a plan. must be unique within the context of a repo.
int64 original_flow_id = 14
string repo_id = 2
repo id is a string identifier for the repo, and repo_guid is the globally unique ID of the repo.
string repo_guid = 15
string plan_id = 3
plan id e.g. a scheduled set of operations (or system) that created this operation.
string instance_id = 11
instance ID that the operation is attributed to, not necessarily the same as the instance that created it.
string original_instance_keyid = 16
original instance guid is the verifiable instance that created the operation. Only set for remote operations created by sync.
string snapshot_id = 8
optional snapshot id if associated with a snapshot.
OperationStatus status = 4
int64 unix_time_start_ms = 5
required, unix time in milliseconds of the operation's creation (ID is derived from this)
int64 unix_time_end_ms = 6
ptional, unix time in milliseconds of the operation's completion
string display_message = 7
optional, human readable context message, typically an error message.
string logref = 9
logref can point to arbitrary logs associated with the operation.
oneof op
operation_backup = 100
operation_index_snapshot = 101
operation_forget = 102
operation_prune = 103
operation_restore = 104
operation_stats = 105
operation_run_hook = 106
operation_check = 107
operation_run_command = 108
message
operations.proto:89Used in:
optional last_status = 3
repeated errors = 4
bool dry_run = 5
indicates this was a dry run backup (no snapshot created)
message
operations.proto:114OperationCheck tracks a check operation.
Used in:
string output = 1
output of the check operation.
string output_logref = 2
logref of the check output.
message
operations.proto:61OperationEvent is used in the wireformat to stream operation changes to clients
Used as response type in: Backrest.GetOperationEvents
Used as field type in:
oneof event
keep_alive = 1
created_operations = 2
updated_operations = 3
deleted_operations = 4
OperationEventType indicates whether the operation was created or updated
EVENT_UNKNOWN = 0
EVENT_CREATED = 1
EVENT_UPDATED = 2
EVENT_DELETED = 3
message
operations.proto:102OperationForget tracks a forget operation.
Used in:
repeated forget = 1
optional policy = 2
message
operations.proto:96OperationIndexSnapshot tracks that a snapshot was detected by backrest.
Used in:
optional snapshot = 2
the snapshot that was indexed.
bool forgot = 3
tracks whether this snapshot is forgotten yet.
message
operations.proto:11Used as response type in: Backrest.GetOperations
Used as field type in:
repeated operations = 1
message
operations.proto:108OperationPrune tracks a prune operation.
Used in:
string output = 1
output of the prune.
string output_logref = 2
logref of the prune output.
message
operations.proto:127OperationRestore tracks a restore operation.
Used in:
string path = 1
path in the snapshot to restore.
string target = 2
location to restore it to.
optional last_status = 3
status of the restore.
message
operations.proto:120OperationRunCommand tracks a long running command. Commands are grouped into a flow ID for each session.
Used in:
string command = 1
string output_logref = 2
int64 output_size_bytes = 3
not necessarily authoritative, tracked as an optimization to allow clients to avoid fetching very large outputs.
message
operations.proto:139OperationRunHook tracks a hook that was run.
Used in:
int64 parent_op = 4
ID of the operation that ran the hook.
string name = 1
description of the hook that was run. typically repo/hook_idx or plan/hook_idx.
string output_logref = 2
logref of the hook's output. DEPRECATED.
Hook.Condition condition = 3
triggering condition of the hook.
message
operations.proto:134OperationStats tracks a stats operation.
Used in:
optional stats = 1
Used in: ,
STATUS_UNKNOWN = 0
used to indicate that the status is unknown.
STATUS_PENDING = 1
used to indicate that the operation is pending.
STATUS_INPROGRESS = 2
used to indicate that the operation is in progress.
STATUS_SUCCESS = 3
used to indicate that the operation completed successfully.
STATUS_WARNING = 7
used to indicate that the operation completed with warnings.
STATUS_ERROR = 4
used to indicate that the operation failed.
STATUS_SYSTEM_CANCELLED = 5
indicates operation cancelled by the system.
STATUS_USER_CANCELLED = 6
indicates operation cancelled by the user.
message
config.proto:119Used in: , , , ,
string id = 1
unique but human readable ID for this plan.
string repo = 2
ID of the repo to use.
repeated string paths = 4
paths to include in the backup.
repeated string excludes = 5
glob patterns to exclude.
repeated string iexcludes = 9
case insensitive glob patterns to exclude.
optional schedule = 12
schedule for the backup.
optional retention = 7
retention policy for snapshots.
repeated hooks = 8
hooks to run on events for this plan.
repeated string backup_flags = 10
extra flags to set when running a backup command.
bool skip_if_unchanged = 13
skip the backup if no changes are detected.
message
crypto.proto:19Used in:
string keyid = 1
a unique identifier generated as the SHA256 of the public key
string ed25519priv = 2
raw base64-encoded ed25519 private key seed.
string ed25519pub = 3
raw base64-encoded ed25519 public key.
message
config.proto:173Used in:
optional schedule = 2
int64 max_unused_bytes = 3
max unused bytes before running prune.
double max_unused_percent = 4
max unused percent before running prune.
message
crypto.proto:14Used in: ,
string keyid = 1
a unique identifier generated as the SHA256 of the public key.
string ed25519pub = 2
raw base64-encoded ed25519 public key.
message
config.proto:101Used in: , , , , , ,
string id = 1
unique but human readable ID for this repo.
string uri = 2
URI of the repo.
string guid = 11
a globally unique ID for this repo. Should be derived as the 'id' field in `restic cat config --json`.
string password = 3
plaintext password
repeated string env = 4
extra environment variables to set for restic.
repeated string flags = 5
extra flags set on the restic command.
optional prune_policy = 6
policy for when to run prune.
optional check_policy = 9
policy for when to run check.
repeated hooks = 7
hooks to run on events for this repo.
bool auto_unlock = 8
automatically unlock the repo when needed.
bool auto_initialize = 12
whether the repo should be auto-initialized if not found.
optional command_prefix = 10
modifiers for the restic commands
bool shared = 13
if true, this repo is pushed to all authorized clients with read-config permission
string origin_instance_id = 14
set when this repo was pushed from a remote instance; marks it as non-editable
optional forget_policy = 15
optional repo-level forget policy. If set, overrides per-plan retention policies.
message
restic.proto:95Used in:
int64 total_size = 1
int64 total_uncompressed_size = 2
double compression_ratio = 3
int64 total_blob_count = 5
int64 snapshot_count = 6
message
restic.proto:8ResticSnapshot represents a restic snapshot.
Used in: , ,
string id = 1
int64 unix_time_ms = 2
string hostname = 3
string username = 4
string tree = 5
tree hash
string parent = 6
parent snapshot's id
repeated string paths = 7
repeated string tags = 8
optional summary = 9
added in 0.17.0 restic outputs the summary in the snapshot
message
restic.proto:85RestoreProgressEvent represents a single entry in the restore progress stream.
Used in:
string message_type = 1
"summary" or "status"
double seconds_elapsed = 2
int64 total_bytes = 3
int64 bytes_restored = 4
int64 total_files = 5
int64 files_restored = 6
double percent_done = 7
0.0 - 1.0
message
config.proto:151Used in: , ,
oneof policy
int32 policy_keep_last_n = 10
policy_time_bucketed = 11
bool policy_keep_all = 12
message
config.proto:158Used in:
int32 hourly = 1
keep the last n hourly snapshots.
int32 daily = 2
keep the last n daily snapshots.
int32 weekly = 3
keep the last n weekly snapshots.
int32 monthly = 4
keep the last n monthly snapshots.
int32 yearly = 5
keep the last n yearly snapshots.
int32 keep_last_n = 6
keep the last n snapshots regardless of age.
message
config.proto:188Used in: , , ,
oneof schedule
bool disabled = 1
disable the schedule.
string cron = 2
cron expression describing the schedule.
int32 maxFrequencyDays = 3
max frequency of runs in days.
int32 maxFrequencyHours = 4
max frequency of runs in hours.
Schedule.Clock clock = 5
clock to use for scheduling.
Used in:
CLOCK_DEFAULT = 0
same as CLOCK_LOCAL
CLOCK_LOCAL = 1
CLOCK_UTC = 2
CLOCK_LAST_RUN_TIME = 3
message
crypto.proto:7Used in: , ,
string keyid = 1
a unique identifier generated as the SHA256 of the public key used to sign the message.
bytes payload = 2
the payload
bytes signature = 3
the signature of the payload
int64 timestampMillis = 4
the timestamp in milliseconds since epoch when the message was signed. Must be within 5 minutes of the current time.
message
restic.proto:20Used in:
int64 files_new = 1
int64 files_changed = 2
int64 files_unmodified = 3
int64 dirs_new = 4
int64 dirs_changed = 5
int64 dirs_unmodified = 6
int64 data_blobs = 7
int64 tree_blobs = 8
int64 data_added = 9
int64 total_files_processed = 10
int64 total_bytes_processed = 11
double total_duration = 12
message
service.proto:222Used in:
repeated int64 flow_id = 1
repeated int64 timestamp_ms = 2
repeated int64 duration_ms = 3
repeated OperationStatus status = 4
repeated int64 bytes_added = 5
message
service.proto:206Used in:
string id = 1
int64 backups_failed_30days = 2
int64 backups_warning_last_30days = 3
int64 backups_success_last_30days = 4
int64 bytes_scanned_last_30days = 5
int64 bytes_added_last_30days = 6
int64 total_snapshots = 7
int64 bytes_scanned_avg = 8
int64 bytes_added_avg = 9
int64 next_backup_time_ms = 10
optional recent_backups = 11
Charts
recent backups
message
config.proto:311Used in:
string name = 1
oneof password
string password_bcrypt = 2