Schemas

Download schema

AgentCommandStatus

string

BackupJob

id

string · required

Formatted backup job ID.

Example: job_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

type

BackupJobType · required

status

BackupJobStatus · required

pending while storage is set up and until the recovery document is saved in the Backup Chief app, active while it runs on schedule, paused, or deleting while its backups are deleted.

status_label

string · required

The status as the Backup Chief app shows it, naming the next step while the job is pending.

Example: Save recovery document

provisioning_state

BackupJobProvisioningState · required

The step the storage setup reached.

required

object · required

The storage destination that keeps the main copy.

source_summary

string · required

One line describing what the job backs up.

Example: /var/www

required

What the job backs up: FileBackupSource for file, MySqlBackupSource for mysql, PostgreSqlBackupSource for postgresql. Passwords are never returned.

object · required

How many backups are kept.

retention_label

string · required

The keep policy in words.

Example: Keeps the last 12 backups, 7 daily and 4 weekly.

object · required

When the agent checks the repository, as cron expressions in UTC.

repository_bytes

integer | null · required

Bytes the main repository last reported, null until it was measured.

last_run_at

string | null · required

last_full_success_at

string | null · required

paused_at

string | null · required

created_at

string · required

BackupJobIntegrityDataMode

string

How the data integrity checks of a backup job are scheduled: auto spreads the checks over the retention period.

BackupJobProvisioningErrorCode

string

Why the storage setup of a backup job stopped.

BackupJobProvisioningState

string

BackupJobRecoveryState

string

BackupJobScheduleKind

string

BackupJobSchedulePreset

string

BackupJobStatus

string

BackupJobType

string

BackupRepository

id

string · required

Formatted repository ID.

Example: repository_01j8q8zk2f4m6n7p9r1s3t5v7x

role

BackupRepositoryRole · required

main for the repository backups are written to, extra_copy for a copy of it at another storage destination.

storage_destination

object | null · required

The storage destination that keeps the repository, null when it was deleted.

status

BackupRepositoryStatus · required

provisioning_state

BackupJobProvisioningState · required

healthy

boolean · required

Whether the repository is active.

repository_bytes

integer | null · required

Bytes the repository last reported, null until it was measured.

initial_sync_completed_at

string | null · required

last_copy_at

string | null · required

When backups were last copied to an extra copy.

last_check_at

string | null · required

detached_at

string | null · required

BackupRepositoryRole

string

The role of a repository of a backup job: the main repository backups are written to, or an extra copy.

BackupRepositoryStatus

string

BackupRun

id

string · required

Formatted run ID.

Example: run_01j8q8zk2f4m6n7p9r1s3t5v7x

object · required

kind

BackupRunKind · required

backup for a backup, or the maintenance operation the run performed.

trigger

BackupRunTrigger · required

manual for a run someone started, scheduled for a run the schedule started.

status

BackupRunStatus · required

The state of the run as the agent reported it.

status_label

string · required

The outcome as the Backup Chief app shows it, which also accounts for extra copies that failed.

Example: Succeeded

required

summary

string | null · required

Short summary the agent reported.

source_files

required

Files the backup read, null for maintenance runs and until reported.

source_bytes

required

Bytes the backup read, null for maintenance runs and until reported.

stored_bytes

required

New bytes the backup added to the repository after deduplication, null for maintenance runs and until reported.

statistics

string[] · required

The reported figures as the Backup Chief app shows them.

Example: ["1,204 files","2.3 GB processed","+12 MB added"]

repository_bytes

integer | null · required

Size of the main repository after the run, null until reported.

repository_bytes_delta

integer | null · required

How much the main repository grew or shrank, null until reported.

snapshots_count

string · required

Snapshots the backup made: one for a file backup, one per database for a database backup.

available_snapshots_count

string · required

Snapshots that can still be restored.

restorable

boolean · required

Whether the run is a recovery point whose snapshots can all still be restored.

kept_forever_at

string | null · required

When the recovery point was set to be kept forever, null when the job's retention policy applies.

has_log

boolean · required

Whether a complete log of the run can be read from the log endpoint.

object[] · required

The result per repository: the main repository and each extra copy the run wrote to or copied to.

scheduled_for

string | null · required

The minute a scheduled run was due, null for manual runs.

started_at

string | null · required

finished_at

string | null · required

created_at

string · required

BackupRunKind

string

BackupRunResultCode

string

BackupRunStatus

string

BackupRunTrigger

string

What started a run: a person or API call, or the schedule.

CreateDownloadRequest

snapshot

string · required

Formatted ID of the snapshot to download from, as listed by the job's snapshots.

Example: snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x

path

string | null · maxLength: 4096

For a file backup: the absolute path of the file or directory to download, inside the job's backed-up path. Not used for database backups, which download the snapshot's database dump.

Example: /var/www/shop/storage/invoices

path_type

string | null · enum

For a file backup: whether the path is a file or a directory.

Enum values:

file

DatabaseSelectionMode

string

Which databases a database backup job backs up: every database the user can read, the listed databases, or all but the listed databases.

DatabaseTableSelectionMode

string

Which tables a database backup job backs up: all tables, only the listed tables, or all but the listed tables.

Download

id

string · required

Formatted download ID.

Example: download_01j8q8zk2f4m6n7p9r1s3t5v7x

object · required

snapshot_id

string · required

Formatted ID of the snapshot the download is made from.

Example: snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x

run_id

string · required

Formatted ID of the backup run that made the snapshot.

Example: run_01j8q8zk2f4m6n7p9r1s3t5v7x

repository

object | null · required

The repository the download is read from, null for downloads that predate extra copies.

kind

DownloadKind · required

file or directory for a file backup, database for a database dump.

name

string · required

File name of the ZIP.

Example: invoices-4f2a9c1d.zip

status

DownloadStatus · required

queued, then inspecting while the size is checked and preparing while the ZIP is made, ready to download until it expires, or failed, cancelled or expired. expiring while a ready ZIP is deleted.

status_label

string · enum · required

The status as the Backup Chief app shows it.

Enum values:

Queued

Checking size

Preparing ZIP

Ready

Deleting

Failed

Cancelled

Expired

Example: Preparing ZIP

downloadable

boolean · required

Whether the ZIP can be downloaded now: create a download URL for it.

source_bytes

integer | null · required

Bytes of backup data the download contains, null until checked.

archive_bytes

integer | null · required

Size of the ZIP, null until it is ready.

uploaded_bytes

integer · required

Bytes of the ZIP uploaded so far while it is prepared.

sha256

string | null · required

SHA-256 checksum of the ZIP, null until it is ready.

required

failure_message

string | null · required

The failure explained, null unless it failed.

download_count

integer · required

How often the ZIP was downloaded.

requested_by

string | null · required

Name of the team member who requested the download, null when a team access token requested it or the member left the team.

created_at

string · required

started_at

string | null · required

ready_at

string | null · required

expires_at

string | null · required

When the ZIP is deleted, or was deleted.

last_downloaded_at

string | null · required

DownloadFailureCode

string

Why a download could not be prepared.

DownloadKind

string

DownloadStatus

string

FileBackupSource

paths

string[] · required

Directories that are backed up.

excludes

string[] · required

Files and folders that are skipped.

InspectSourceRequest

Validates a source to test, for a new backup job on a server or for a change to an existing job.

object · required

What to back up. The fields depend on the type, see the description of each field. Fields left out keep their value on an existing job.

job

string

Formatted ID of the backup job whose source changes. The source fields left out keep the job's value, including its stored database password. Leave it out to test the source of a new job.

Example: job_01j8q8zk2f4m6n7p9r1s3t5v7x

server

string

Formatted ID of the enrolled server that tests the source of a new job.

Example: server_01j8q8zk2f4m6n7p9r1s3t5v7x

type

string · enum

The type of the new job.

Enum values:

file

mysql

postgresql

LocalStorageSettings

path

string · required

Path relative to the application's storage directory.

MySqlBackupSource

host

string · required

port

integer · required

username

string · required

password_set

boolean · required

Whether a password is stored. It is never returned.

password_file

string | null · required

selection_mode

DatabaseSelectionMode · required

Which databases a database backup job backs up: every database the user can read, the listed databases, or all but the listed databases.

databases

string[] · required

include_routines

boolean · required

include_events

boolean · required

custom_flags

string[] · required

table_selection

object | null · required

The tables the job is limited to, null for all tables.

PostgreSqlBackupSource

host

string · required

port

integer · required

username

string · required

password_set

boolean · required

Whether a password is stored. It is never returned.

password_file

string | null · required

connection_database

string · required

selection_mode

DatabaseSelectionMode · required

Which databases a database backup job backs up: every database the user can read, the listed databases, or all but the listed databases.

databases

string[] · required

table_selection

object | null · required

The tables the job is limited to, null for all tables.

QueueMaintenanceRequest

operation

string · enum · required

forget removes the backups the keep policy no longer needs, prune frees the storage they used at every storage destination, snapshot_inventory rechecks which backups are still stored.

Enum values:

forget

prune

snapshot_inventory

S3StorageSettings

endpoint

string · required

region

string · required

bucket

string · required

root_path

string · required

Path inside the bucket that holds the repositories.

Example: backupchief

SaveBackupJobRequest

Validates a backup job and turns its source into the configuration of its type, the same way the job forms do.

name

string · maxLength: 255 · required

Display name of the backup job.

Example: Website files

server

string · required

Formatted ID of the enrolled server that runs the job. It cannot be changed later.

Example: server_01j8q8zk2f4m6n7p9r1s3t5v7x

storage_destination

string · required

Formatted ID of the storage destination that keeps the main copy. It cannot be changed later.

Example: storage_01j8q8zk2f4m6n7p9r1s3t5v7x

type

string · enum · required

What the job backs up. It cannot be changed later.

Enum values:

file

mysql

postgresql

object · required

What to back up. The fields depend on the type, see the description of each field. Fields left out keep their value on an existing job.

source_inspection

string | null

Formatted ID of a completed, successful source test of exactly this source, at most 10 minutes old. Required when creating a job and when changing the source of a job.

Example: inspection_01j8q8zk2f4m6n7p9r1s3t5v7x

object

When the job runs. A new job runs every day at the next full hour when it is left out; fields left out keep the schedule of an existing job.

object

How many backups to keep. Tiers left out keep their value, or the default for the schedule on a new job. Tiers the schedule makes redundant are folded into last.

attempt_id

string

ULID that identifies this creation attempt. Retrying with the same ID and the same job returns the job created the first time instead of a second job.

Example: 01j8q8zk2f4m6n7p9r1s3t5v7x

SaveServerRequest

name

string · maxLength: 255 · required

Display name of the server.

Example: Web server

agent_auto_updates

boolean | null

Whether the server installs new agent releases automatically, null to follow the team setting.

SaveStorageDestinationRequest

Validates the settings of a storage destination and turns them into the driver form state the storage services take.

name

string · maxLength: 255 · required

Display name of the destination, unique within the team.

Example: Production S3

driver

string · enum · required

Storage driver. local is only available in development.

Enum values:

sftp

Example: s3

object · required

The settings of the driver; only the fields of the driver may be given. Fields left out keep their value on an existing destination of the same driver.

Server

id

string · required

Formatted server ID.

Example: server_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

hostname

string | null · required

Hostname the agent reported, null until it enrolls.

Example: web-1.example.com

status

ServerStatus · required

pending until an agent enrolls with an enrollment token, enrolled while an agent is set up, revoked once its agent was revoked.

connected

boolean · required

Whether the server is enrolled and its agent reported within the last few minutes.

platform

string | null · required

Operating system and CPU architecture the agent reported.

Example: linux/amd64

object · required

last_contact_at

string | null · required

When the agent last contacted Backup Chief.

enrolled_at

string | null · required

revoked_at

string | null · required

created_at

string · required

active_jobs_count

integer

Number of active backup jobs on the server.

jobs_count

integer

Number of backup jobs on the server, including paused ones.

object

The one-time enrollment token, only included in the response that issued it.

ServerStatus

string

The enrollment status of a server: pending until an agent enrolls, enrolled while an agent is set up, revoked once its agent was revoked.

SftpAuthMethod

string

How an SFTP storage destination signs in: a password, or an Ed25519 key generated in the Backup Chief app.

SftpStorageSettings

host

string · required

port

integer · required

username

string · required

root_path

string · required

auth_method

SftpAuthMethod · required

password, or ed25519 for a key generated in Backup Chief.

public_key

string | null · required

Public key to authorize on the SFTP server, null for password authentication.

fingerprint

string | null · required

Fingerprint of the public key, null for password authentication.

host_keys

string[] · required

Host keys of the SFTP server pinned at the first connection. Connections presenting another key are refused.

Snapshot

id

string · required

Formatted snapshot ID.

Example: snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x

snapshot_id

string · required

The restic snapshot ID in the repository the backup wrote to.

Example: 4f2a9c1d8e7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f

object · required

run_id

string · required

Formatted ID of the backup run that made the snapshot. Keeping forever and expiring work on this run, the recovery point.

Example: run_01j8q8zk2f4m6n7p9r1s3t5v7x

availability

SnapshotAvailability · required

Whether the snapshot can still be restored from the repository the backup wrote to.

source_bytes

integer | null · required

Bytes the backup read for this snapshot.

stored_bytes

integer | null · required

New bytes this snapshot added to the repository after deduplication.

database

object | null · required

The database of a database backup snapshot, null for file backups.

kept_forever_at

string | null · required

When the recovery point was set to be kept forever, null when the job's retention policy applies.

object[] · required

The copies of the snapshot in extra copy repositories.

taken_at

string | null · required

When the backup that made the snapshot finished.

created_at

string · required

SnapshotAvailability

string

SourceInspection

id

string · required

Formatted source inspection ID, pass it as source_inspection when saving the backup job.

Example: inspection_01j8q8zk2f4m6n7p9r1s3t5v7x

object · required

status

AgentCommandStatus · required

pending until the agent picks the test up, acknowledged while it runs, then completed with a result, or expired when the agent did not run it in time.

successful

boolean · required

Whether the source can be used: the test completed successfully. The job must be saved within 10 minutes of completion.

result

object | null · required

What the agent found, null until the test completed.

guidance

object | null · required

How to fix a failed test, null unless the test failed.

expires_at

string · required

When the agent must have picked the test up.

completed_at

string | null · required

created_at

string · required

SourceInspectionFailureStage

string

SourceInspectionResultCode

string

The result of a source inspection: success, or why the agent could not use the source.

StorageDestination

id

string · required

Formatted storage destination ID.

Example: storage_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

driver

StorageDriver · required

Where repositories are stored: s3 for S3-compatible storage, sftp for an SFTP server, local for development storage.


`s3` The S3 storage driver, which can be used with any S3-compatible storage services.
`sftp` SFTP storage authenticated by password or a generated Ed25519 key.
`local` Development only storage driver, should never be used in production.

location

string · required

Human-readable location of the destination.

Example: https://s3.example.com/backups/backupchief

required

The settings of the driver: S3StorageSettings for s3, SftpStorageSettings for sftp, LocalStorageSettings for local. Credentials are never returned.

credentials_updated_at

string | null · required

When the credentials were last replaced, null when they never changed.

servers_on_previous_credentials

integer · required

Servers that did not apply the latest credentials yet. Wait until this is 0 before revoking the old credentials at the provider.

in_use

boolean · required

Whether a backup job keeps its main copy or an extra copy here, which prevents deleting the destination and changing its location.

jobs_count

integer · required

Backup jobs that keep their main copy here.

extra_copies_count

integer · required

Backup jobs that keep an extra copy here.

stored_bytes

integer | null · required

Bytes the repositories at this destination last reported, null until any was measured.

created_at

string · required

StorageDriver

string


`s3` The S3 storage driver, which can be used with any S3-compatible storage services.
`sftp` SFTP storage authenticated by password or a generated Ed25519 key.
`local` Development only storage driver, should never be used in production.

Team

slug

string · required

Team slug, the value of the X-Chief-Team header.

Example: acme

name

string · required

timezone

string | null · required

Timezone of the team.

Example: Europe/Amsterdam

agent_auto_updates

boolean · required

Whether servers install new agent releases automatically, unless a server overrides it.

object · required

The plan limits of the team. A null limit is unlimited.