{
"openapi": "3.1.2",
"info": {
"title": "Backup Chief API v1",
"version": "1.0.0",
"description": "Configure and observe the authenticated team's backups: servers and their agents, storage destinations, backup jobs, runs, snapshots and hosted downloads."
},
"servers": [
{
"url": "https:\/\/backup.chief.app\/api\/v1"
}
],
"tags": [
{
"name": "Team",
"description": "The team the request acts on, with its plan limits and their usage."
},
{
"name": "Servers",
"description": "Endpoints for the servers of the team. Each server runs the Backup Chief agent, which runs its backup jobs and reports their results."
},
{
"name": "Storage destinations",
"description": "Endpoints for the storage destinations of the team: S3-compatible storage or SFTP servers the team owns, where the agents write the encrypted backup repositories. Credentials can be set but are never returned."
},
{
"name": "Backup jobs",
"description": "Endpoints for the backup jobs of the team. A job backs up files or databases of one server to a storage destination on a schedule. The agent on the server runs it, so changes and runs take effect when the agent next checks in."
},
{
"name": "Source inspections",
"description": "Endpoints to test the source of a backup job on its server before saving it. The agent checks it can read the directories, or sign in to the database and list the selected databases and tables."
},
{
"name": "Runs",
"description": "Endpoints for the runs of the team's backup jobs: backups and maintenance operations such as retention cleanup, pruning and integrity checks. A backup run is a recovery point, which can be kept forever or expired."
},
{
"name": "Snapshots",
"description": "Endpoints for the restic snapshots of the team's backup jobs. Every backup run makes one snapshot for a file backup or one per database for a database backup. Restore them with the agent or restic, or prepare a hosted download."
},
{
"name": "Downloads",
"description": "Endpoints for hosted downloads: ZIPs of a file, a directory or a database dump from a snapshot, prepared by Backup Chief so they can be downloaded without access to the server. A download copies backup contents out of the team's own storage for a limited time, so only prepare one when it is needed. Restores on the team's own servers with the agent or restic need no download."
}
],
"security": [
{
"ctp": []
},
{
"openid": []
},
{
"ctt": []
}
],
"paths": {
"\/team": {
"get": {
"operationId": "team.single",
"description": "Get the team the token acts on, with its plan limits and their usage. Any Backup Chief read scope grants access.",
"summary": "Get the team",
"tags": [
"Team"
],
"responses": {
"200": {
"description": "`Team`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Team"
}
},
"required": [
"data"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:read"
]
},
{
"openid": [
"backupchief:storage:read"
]
},
{
"openid": [
"backupchief:jobs:read"
]
},
{
"openid": [
"backupchief:downloads:read"
]
},
{
"ctp": [
"backupchief:servers:read"
]
},
{
"ctp": [
"backupchief:storage:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:downloads:read"
]
},
{
"ctt": [
"backupchief:servers:read"
]
},
{
"ctt": [
"backupchief:storage:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:downloads:read"
]
}
]
}
},
"\/servers": {
"get": {
"operationId": "servers.index",
"description": "List the team's servers by name.",
"summary": "List servers",
"tags": [
"Servers"
],
"parameters": [
{
"name": "query",
"in": "query",
"description": "Search results by name.",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"example": "production"
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return servers in this state: attention for servers whose agent is offline or rejected its configuration, connected, offline, pending or revoked.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"attention",
"connected",
"offline",
"pending",
"revoked",
null
]
},
"example": "attention"
}
],
"responses": {
"200": {
"description": "Paginated set of `Server`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/Server"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:read"
]
},
{
"ctp": [
"backupchief:servers:read"
]
},
{
"ctt": [
"backupchief:servers:read"
]
}
]
},
"post": {
"operationId": "servers.create",
"description": "Add a pending server to the team. The response includes a one-time enrollment token, valid for one hour, and the setup command to run on the server. The token is not returned again: issue a new one when it is lost or expired.",
"summary": "Create a server",
"tags": [
"Servers"
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveServerRequest"
}
}
}
},
"responses": {
"201": {
"description": "The server was created.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
}
},
"\/storage-destinations": {
"get": {
"operationId": "storageDestinations.index",
"description": "List the team's storage destinations by name.",
"summary": "List storage destinations",
"tags": [
"Storage destinations"
],
"parameters": [
{
"name": "query",
"in": "query",
"description": "Search results by name.",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"example": "production"
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return destinations in this state: attention for destinations with servers still on previous credentials, in_use for destinations that hold a main or extra copy of a backup job, unused for the others.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"attention",
"in_use",
"unused",
null
]
},
"example": "in_use"
}
],
"responses": {
"200": {
"description": "Paginated set of `StorageDestination`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/StorageDestination"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:storage:read"
]
},
{
"ctp": [
"backupchief:storage:read"
]
},
{
"ctt": [
"backupchief:storage:read"
]
}
]
},
"post": {
"operationId": "storageDestinations.create",
"description": "Add an S3 or SFTP storage destination. Backup Chief first verifies it can list, read, write, and delete at the destination; nothing is saved when that fails. SFTP destinations created through the API sign in with a password; keys can only be generated in the Backup Chief app. The host keys the SFTP server presents at the first connection are pinned.",
"summary": "Create a storage destination",
"tags": [
"Storage destinations"
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveStorageDestinationRequest"
}
}
}
},
"responses": {
"201": {
"description": "The storage destination was created.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/StorageDestination"
}
},
"required": [
"data"
]
}
}
}
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:storage:write"
]
},
{
"ctp": [
"backupchief:storage:write"
]
},
{
"ctt": [
"backupchief:storage:write"
]
}
]
}
},
"\/jobs": {
"get": {
"operationId": "backupJobs.index",
"description": "List the team's backup jobs by name. The query matches the name, the backed-up path and the names of the server and storage destination.",
"summary": "List backup jobs",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "query",
"in": "query",
"description": "Search results by name.",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"example": "production"
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return jobs in this state: attention for jobs with a problem to look at, or a job status.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"attention",
"pending",
"active",
"paused",
"deleting",
null
]
},
"example": "attention"
},
{
"name": "server",
"in": "query",
"description": "Only return the jobs of this server.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "server_01j8q8zk2f4m6n7p9r1s3t5v7x"
}
],
"responses": {
"200": {
"description": "Paginated set of `BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
},
"post": {
"operationId": "backupJobs.create",
"description": "Create a backup job on an enrolled server. Test the source first with the source inspections endpoint and pass the ID of the successful test as source_inspection; it must test exactly this source and be at most 10 minutes old. The job starts as pending while Backup Chief sets up its repository. It only starts running after its recovery document is saved and confirmed in the Backup Chief app.",
"summary": "Create a backup job",
"tags": [
"Backup jobs"
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveBackupJobRequest"
}
}
}
},
"responses": {
"201": {
"description": "The backup job was created.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/source-inspections": {
"post": {
"operationId": "sourceInspections.create",
"description": "Ask the agent of a server to test a backup source. The agent runs the test the next time it checks in, usually within a minute: poll the inspection until it completed, then pass its ID as source_inspection when creating the job, or when changing the source of a job (test with the job argument), within 10 minutes. The tested source must match the saved source exactly.",
"summary": "Test a backup source",
"tags": [
"Source inspections"
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/InspectSourceRequest"
}
}
}
},
"responses": {
"201": {
"description": "The test was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/SourceInspection"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/runs": {
"get": {
"operationId": "runs.index",
"description": "List the runs of all the team's backup jobs, newest first.",
"summary": "List runs",
"tags": [
"Runs"
],
"parameters": [
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return runs with this status.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"pending",
"running",
"complete",
"partial",
"failed",
"cancelled",
"skipped",
"unresolved",
null
]
}
},
{
"name": "kind",
"in": "query",
"description": "Only return backups, or runs of this maintenance operation.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"backup",
"forget",
"prune",
"check_metadata",
"check_data",
"snapshot_inventory",
null
]
}
},
{
"name": "trigger",
"in": "query",
"description": "Only return runs someone started (manual) or the schedule started (scheduled).",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"manual",
"scheduled",
null
]
}
},
{
"name": "job",
"in": "query",
"description": "Only return the runs of this backup job.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "job_01j8q8zk2f4m6n7p9r1s3t5v7x"
},
{
"name": "server",
"in": "query",
"description": "Only return the runs on this server.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "server_01j8q8zk2f4m6n7p9r1s3t5v7x"
}
],
"responses": {
"200": {
"description": "Paginated set of `BackupRun`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/jobs\/{job}\/snapshots": {
"get": {
"operationId": "backupJobs.snapshots",
"description": "List the snapshots the job's backups made, newest first.",
"summary": "List the snapshots of a backup job",
"tags": [
"Snapshots"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "availability",
"in": "query",
"description": "Only return snapshots with this availability, available for the snapshots that can still be restored.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"available",
"expired",
"unknown",
null
]
}
}
],
"responses": {
"200": {
"description": "Paginated set of `Snapshot`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/Snapshot"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/downloads": {
"get": {
"operationId": "downloads.index",
"description": "List the hosted downloads of all the team's backup jobs, newest first.",
"summary": "List downloads",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return downloads that are available (ready and not expired), in_progress (being prepared or deleted) or history (failed, cancelled or expired).",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"available",
"in_progress",
"history",
null
]
}
},
{
"name": "job",
"in": "query",
"description": "Only return the downloads of this backup job.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "job_01j8q8zk2f4m6n7p9r1s3t5v7x"
}
],
"responses": {
"200": {
"description": "Paginated set of `Download`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/Download"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:downloads:read"
]
},
{
"ctp": [
"backupchief:downloads:read"
]
},
{
"ctt": [
"backupchief:downloads:read"
]
}
]
}
},
"\/jobs\/{job}": {
"get": {
"operationId": "backupJobs.single",
"description": "Get one of the team's backup jobs with its source, schedule, retention and storage state. Passwords are never returned.",
"summary": "Get a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
},
"patch": {
"operationId": "backupJobs.update",
"description": "Change the name, source, schedule or retention of a backup job. Fields left out keep their value, including a stored database password. A changed source must pass a new source test first: pass the ID of a successful test of the changed source, made with the job argument, as source_inspection. The server, storage destination and type cannot be changed.",
"summary": "Update a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveBackupJobRequest"
}
}
}
},
"responses": {
"200": {
"description": "`BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
},
"delete": {
"operationId": "backupJobs.delete",
"description": "Delete a paused backup job once its agent dropped it from its configuration and no run is pending or running. Without delete_repository only the job and its history are deleted and its backups stay in storage, where restic can still restore them with the recovery document. With delete_repository the job turns deleting and its repositories are deleted from storage in the background before the job is removed.",
"summary": "Delete a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "delete_repository",
"in": "query",
"description": "Also delete the job's repositories and every backup in them from storage. Without it only the job and its history are deleted from Backup Chief and the backups stay in storage.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"202": {
"description": "The backups are being deleted, the job is removed once they are.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"204": {
"description": "The backup job was deleted.",
"content": {
"application\/json": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
},
"409": {
"description": "The job is not paused yet, its agent did not drop it yet, or a run is still pending or running. The message says which.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/pause": {
"post": {
"operationId": "backupJobs.pause",
"description": "Stop running an active backup job on its schedule. Its backups and history are kept. Queued runs are cancelled, a running backup may still finish, and the schedule stops once the agent checks in. A job must be paused before it can be deleted.",
"summary": "Pause a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/resume": {
"post": {
"operationId": "backupJobs.resume",
"description": "Run a paused backup job on its schedule again once the agent checks in.",
"summary": "Resume a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/run": {
"post": {
"operationId": "backupJobs.run",
"description": "Queue a backup of an active job outside its schedule. The agent starts it the next time it checks in; follow it in the job's runs.",
"summary": "Run a backup now",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "The backup was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/maintenance": {
"post": {
"operationId": "backupJobs.maintenance",
"description": "Queue a maintenance operation of an active job outside its schedule: remove the backups the keep policy no longer needs, free the storage space they used, or recheck which backups are still stored. The agent starts it the next time it checks in.",
"summary": "Run maintenance now",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/QueueMaintenanceRequest"
}
}
}
},
"responses": {
"202": {
"description": "The maintenance was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/retry-provisioning": {
"post": {
"operationId": "backupJobs.retryProvisioning",
"description": "Continue setting up the storage of a pending job from the last safe step, after its setup stopped with provisioning_error_code. Fix the cause first, such as the storage credentials.",
"summary": "Retry the storage setup",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupJob`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupJob"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/jobs\/{job}\/repositories": {
"get": {
"operationId": "backupJobs.repositories",
"description": "List the restic repositories of a backup job: the main repository first, then its extra copies at other storage destinations. Extra copies are added and managed in the Backup Chief app, because they need the job's recovery password.",
"summary": "List the repositories of a backup job",
"tags": [
"Backup jobs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Array of `BackupRepository`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/BackupRepository"
}
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/jobs\/{job}\/downloads": {
"get": {
"operationId": "backupJobs.downloads",
"description": "List the hosted downloads of one backup job, newest first.",
"summary": "List the downloads of a backup job",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return downloads that are available (ready and not expired), in_progress (being prepared or deleted) or history (failed, cancelled or expired).",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"available",
"in_progress",
"history",
null
]
}
},
{
"name": "job",
"in": "query",
"description": "Only return the downloads of this backup job.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "job_01j8q8zk2f4m6n7p9r1s3t5v7x"
}
],
"responses": {
"200": {
"description": "Paginated set of `Download`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/Download"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:downloads:read"
]
},
{
"ctp": [
"backupchief:downloads:read"
]
},
{
"ctt": [
"backupchief:downloads:read"
]
}
]
},
"post": {
"operationId": "downloads.create",
"description": "Prepare a ZIP from a snapshot of an active or paused job: the database dump of a database backup snapshot, or a file or directory of a file backup snapshot given by its absolute path. The path must be inside the job's backed-up path; whether it exists in the snapshot is checked while the download is prepared, and a path that does not exist fails the download with failure_code source_unavailable. Preparing runs in the background: poll the download until it is ready, then create a download URL. Requesting the same content again while a download of it is being prepared or ready returns that download. The team's plan limits the size, the number of downloads per day and the downloads being prepared at once.",
"summary": "Prepare a download",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/CreateDownloadRequest"
}
}
}
},
"responses": {
"202": {
"description": "The download is being prepared, or an earlier download of the same content is returned.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Download"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:downloads:write"
]
},
{
"ctp": [
"backupchief:downloads:write"
]
},
{
"ctt": [
"backupchief:downloads:write"
]
}
]
}
},
"\/downloads\/{download}": {
"get": {
"operationId": "downloads.single",
"description": "Get one hosted download, to follow its preparation until it is ready.",
"summary": "Get a download",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "download",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Download`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Download"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:downloads:read"
]
},
{
"ctp": [
"backupchief:downloads:read"
]
},
{
"ctt": [
"backupchief:downloads:read"
]
}
]
},
"delete": {
"operationId": "downloads.delete",
"description": "Delete the ZIP of a ready download before it expires. Download URLs created for it stop working. The download stays listed in the history.",
"summary": "Delete a ready download",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "download",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Download`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Download"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"410": {
"description": "The download has no ZIP to delete.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "download_unavailable"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:downloads:write"
]
},
{
"ctp": [
"backupchief:downloads:write"
]
},
{
"ctt": [
"backupchief:downloads:write"
]
}
]
}
},
"\/downloads\/{download}\/cancel": {
"post": {
"operationId": "downloads.cancel",
"description": "Stop preparing a download. A queued download is cancelled right away, one being prepared stops at its next check, and the ZIP of a ready download is deleted.",
"summary": "Cancel a download",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "download",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Download`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Download"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:downloads:write"
]
},
{
"ctp": [
"backupchief:downloads:write"
]
},
{
"ctt": [
"backupchief:downloads:write"
]
}
]
}
},
"\/downloads\/{download}\/url": {
"post": {
"operationId": "downloads.url",
"description": "Create a URL that downloads the ZIP of a ready download. Anyone with the URL can download the backup contents, without signing in, until it expires after 60 minutes, so share it only with whoever needs it. A ready download is kept at least until the URL expires.",
"summary": "Create a download URL",
"tags": [
"Downloads"
],
"parameters": [
{
"name": "download",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The download URL. Anyone with it can download the ZIP until it expires."
},
"expires_at": {
"type": "string",
"description": "When the URL stops working."
}
},
"required": [
"url",
"expires_at"
]
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"410": {
"description": "The download is not ready, or its ZIP was deleted.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "download_unavailable"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:downloads:write"
]
},
{
"ctp": [
"backupchief:downloads:write"
]
},
{
"ctt": [
"backupchief:downloads:write"
]
}
]
}
},
"\/jobs\/{job}\/runs": {
"get": {
"operationId": "backupJobs.runs",
"description": "List the runs of one backup job, newest first.",
"summary": "List the runs of a backup job",
"tags": [
"Runs"
],
"parameters": [
{
"name": "job",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"description": "Number of results per page.",
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
},
{
"name": "page",
"in": "query",
"description": "Page number to return.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "status",
"in": "query",
"description": "Only return runs with this status.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"pending",
"running",
"complete",
"partial",
"failed",
"cancelled",
"skipped",
"unresolved",
null
]
}
},
{
"name": "kind",
"in": "query",
"description": "Only return backups, or runs of this maintenance operation.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"backup",
"forget",
"prune",
"check_metadata",
"check_data",
"snapshot_inventory",
null
]
}
},
{
"name": "trigger",
"in": "query",
"description": "Only return runs someone started (manual) or the schedule started (scheduled).",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"manual",
"scheduled",
null
]
}
},
{
"name": "job",
"in": "query",
"description": "Only return the runs of this backup job.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "job_01j8q8zk2f4m6n7p9r1s3t5v7x"
},
{
"name": "server",
"in": "query",
"description": "Only return the runs on this server.",
"schema": {
"type": [
"string",
"null"
]
},
"example": "server_01j8q8zk2f4m6n7p9r1s3t5v7x"
}
],
"responses": {
"200": {
"description": "Paginated set of `BackupRun`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": [
"string",
"null"
]
},
"last": {
"type": [
"string",
"null"
]
},
"prev": {
"type": [
"string",
"null"
]
},
"next": {
"type": [
"string",
"null"
]
}
},
"required": [
"first",
"last",
"prev",
"next"
]
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"minimum": 1
},
"from": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"last_page": {
"type": "integer",
"minimum": 1
},
"links": {
"type": "array",
"description": "Generated paginator links.",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"label": {
"type": "string"
},
"active": {
"type": "boolean"
}
},
"required": [
"url",
"label",
"active"
]
}
},
"path": {
"type": [
"string",
"null"
],
"description": "Base path for paginator generated URLs."
},
"per_page": {
"type": "integer",
"description": "Number of items shown per page.",
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"description": "Number of the last item in the slice.",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items being paginated.",
"minimum": 0
}
},
"required": [
"current_page",
"from",
"last_page",
"links",
"path",
"per_page",
"to",
"total"
]
}
},
"required": [
"data",
"links",
"meta"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/runs\/{run}": {
"get": {
"operationId": "runs.single",
"description": "Get one run with its outcome, figures and the result per repository, including diagnostics of failures.",
"summary": "Get a run",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupRun`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/runs\/{run}\/log": {
"get": {
"operationId": "runs.log",
"description": "Return the complete log the agent uploaded for the run, as plain text. Logs are kept for a limited time; has_log on the run tells whether one is available.",
"summary": "Get the log of a run",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The run log.",
"content": {
"text\/plain; charset=UTF-8": {
"schema": {
"type": "string"
}
},
"text\/plain": {
"schema": {
"type": "string"
}
}
},
"headers": {
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store, private"
}
}
}
},
"404": {
"description": "The run has no complete log, or it is no longer kept.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/runs\/{run}\/cancel": {
"post": {
"operationId": "runs.cancel",
"description": "Ask the agent to stop a pending or running run. The agent stops it the next time it checks in; follow the run's status. Asking again while a cancellation is pending changes nothing.",
"summary": "Cancel a run",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "The cancellation was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The run already ended.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/runs\/{run}\/retry": {
"post": {
"operationId": "runs.retry",
"description": "Run a finished maintenance operation again with the plan it was started with, such as a retention cleanup that failed for an extra copy. Backups are not retried this way: run the job again instead. The response is the original run; the retry shows up as a new run of the job.",
"summary": "Retry a maintenance run",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "The retry was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The run is a backup, has not finished, or has no saved maintenance plan.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/runs\/{run}\/keep-forever": {
"put": {
"operationId": "runs.keepForever",
"description": "Exclude a backup run and all its snapshots from the job's retention policy, so automatic cleanup never removes them. The job must be active on an enrolled server and every snapshot of the run must still be restorable.",
"summary": "Keep a recovery point forever",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupRun`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The run is not a restorable recovery point, or retention cannot be changed now; the message says why.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
},
"delete": {
"operationId": "runs.useRetentionPolicy",
"description": "Put a recovery point that was kept forever back under the job's retention policy, which may then remove it at its next cleanup.",
"summary": "Stop keeping a recovery point forever",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`BackupRun`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The run is not a recovery point, or retention cannot be changed now; the message says why.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/runs\/{run}\/expire": {
"post": {
"operationId": "runs.expire",
"description": "Ask the agent to remove a backup run's snapshots from its repositories now, regardless of the retention policy. This cannot be undone: the data can no longer be restored once the agent removed it. The newest complete recovery point and recovery points kept forever cannot be expired.",
"summary": "Expire a recovery point",
"tags": [
"Runs"
],
"parameters": [
{
"name": "run",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "The removal was queued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/BackupRun"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The recovery point cannot be expired; the message says why.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:jobs:write"
]
},
{
"ctp": [
"backupchief:jobs:write"
]
},
{
"ctt": [
"backupchief:jobs:write"
]
}
]
}
},
"\/servers\/{server}": {
"get": {
"operationId": "servers.single",
"description": "Get one of the team's servers with its agent status, version and job counts.",
"summary": "Get a server",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Server`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:read"
]
},
{
"ctp": [
"backupchief:servers:read"
]
},
{
"ctt": [
"backupchief:servers:read"
]
}
]
},
"patch": {
"operationId": "servers.update",
"description": "Rename a server or change whether it installs new agent releases automatically. Fields left out keep their value.",
"summary": "Update a server",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveServerRequest"
}
}
}
},
"responses": {
"200": {
"description": "`Server`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
},
"delete": {
"operationId": "servers.delete",
"description": "Delete a pending server that never enrolled. Revoke an enrolled server instead; its history is kept.",
"summary": "Delete a server",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "The server was deleted.",
"content": {
"application\/json": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The server enrolled at some point and can only be revoked.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
}
},
"\/servers\/{server}\/revoke": {
"post": {
"operationId": "servers.revoke",
"description": "Revoke the server's agent credential and cancel its pending work. Backup jobs, runs and snapshots are kept. Revocation cannot reach an offline or compromised machine: also revoke the storage credentials it used. Revoking a revoked server changes nothing.",
"summary": "Revoke a server",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Server`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
}
},
"\/servers\/{server}\/enrollment-token": {
"post": {
"operationId": "servers.enrollmentToken",
"description": "Issue a new one-time enrollment token, valid for one hour, with the setup command to run on the server. Earlier unused tokens stop working. For a pending server the token enrolls its first agent. For an enrolled or revoked server it sets the server up again: the server becomes pending, its current agent is disconnected and its running work is cancelled.",
"summary": "Issue an enrollment token",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "The token was issued.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
}
},
"\/servers\/{server}\/agent-update": {
"post": {
"operationId": "servers.updateAgent",
"description": "Ask the server's agent to install the latest agent release once its current work reaches a safe stopping point. The agent must be connected and support remote updates. When an update is already scheduled, that update is kept.",
"summary": "Update the agent",
"tags": [
"Servers"
],
"parameters": [
{
"name": "server",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Server`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Server"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "The agent cannot be updated now, the message says why.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:servers:write"
]
},
{
"ctp": [
"backupchief:servers:write"
]
},
{
"ctt": [
"backupchief:servers:write"
]
}
]
}
},
"\/snapshots\/{snapshot}": {
"get": {
"operationId": "snapshots.single",
"description": "Get one snapshot with its copies in extra copy repositories.",
"summary": "Get a snapshot",
"tags": [
"Snapshots"
],
"parameters": [
{
"name": "snapshot",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`Snapshot`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/Snapshot"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/source-inspections\/{inspection}": {
"get": {
"operationId": "sourceInspections.single",
"description": "Poll a source test until it completed. successful tells whether the source can be saved; guidance explains how to fix a failed test.",
"summary": "Get a source inspection",
"tags": [
"Source inspections"
],
"parameters": [
{
"name": "inspection",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`SourceInspection`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/SourceInspection"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:jobs:read"
]
},
{
"ctp": [
"backupchief:jobs:read"
]
},
{
"ctt": [
"backupchief:jobs:read"
]
}
]
}
},
"\/storage-destinations\/{destination}": {
"get": {
"operationId": "storageDestinations.single",
"description": "Get one of the team's storage destinations with its settings and the jobs that use it. Credentials are never returned.",
"summary": "Get a storage destination",
"tags": [
"Storage destinations"
],
"parameters": [
{
"name": "destination",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`StorageDestination`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/StorageDestination"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
}
},
"security": [
{
"openid": [
"backupchief:storage:read"
]
},
{
"ctp": [
"backupchief:storage:read"
]
},
{
"ctt": [
"backupchief:storage:read"
]
}
]
},
"patch": {
"operationId": "storageDestinations.update",
"description": "Rename a destination, rotate its credentials, or change its settings. Fields left out keep their value, credentials included. New credentials and settings are verified before they are saved.\n\nOnce a backup job stored a repository at the destination, its driver and location are fixed: only the name and credentials can change. New credentials reach the agents with their next configuration; keep the old credentials valid at the provider until `servers_on_previous_credentials` is 0.",
"summary": "Update a storage destination",
"tags": [
"Storage destinations"
],
"parameters": [
{
"name": "destination",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"$ref": "#\/components\/schemas\/SaveStorageDestinationRequest"
}
}
}
},
"responses": {
"200": {
"description": "`StorageDestination`",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#\/components\/schemas\/StorageDestination"
}
},
"required": [
"data"
]
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"422": {
"$ref": "#\/components\/responses\/ValidationException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "Backup jobs use the destination, so its driver and location cannot change.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:storage:write"
]
},
{
"ctp": [
"backupchief:storage:write"
]
},
{
"ctt": [
"backupchief:storage:write"
]
}
]
},
"delete": {
"operationId": "storageDestinations.delete",
"description": "Delete a destination that no backup job keeps a main or extra copy at. The data at the destination itself is not touched.",
"summary": "Delete a storage destination",
"tags": [
"Storage destinations"
],
"parameters": [
{
"name": "destination",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "The storage destination was deleted.",
"content": {
"application\/json": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#\/components\/responses\/ModelNotFoundException"
},
"401": {
"$ref": "#\/components\/responses\/AuthenticationException"
},
"409": {
"description": "A backup job keeps a copy at the destination.",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"const": "state_conflict"
}
},
"required": [
"message",
"code"
]
}
}
}
}
},
"security": [
{
"openid": [
"backupchief:storage:write"
]
},
{
"ctp": [
"backupchief:storage:write"
]
},
{
"ctt": [
"backupchief:storage:write"
]
}
]
}
}
},
"components": {
"securitySchemes": {
"ctp": {
"type": "http",
"description": "Chief Tools personal access token.",
"scheme": "bearer",
"bearerFormat": "ctp_*"
},
"openid": {
"type": "openIdConnect",
"openIdConnectUrl": "https:\/\/account.chief.app\/.well-known\/openid-configuration"
},
"ctt": {
"type": "http",
"description": "Chief Tools team access token.",
"scheme": "bearer",
"bearerFormat": "ctt_*"
}
},
"schemas": {
"AgentCommandStatus": {
"type": "string",
"x-extensible-enum": [
"pending",
"acknowledged",
"completed",
"cancelled",
"expired"
],
"title": "AgentCommandStatus"
},
"BackupJob": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted backup job ID.",
"examples": [
"job_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string",
"examples": [
"Website files"
]
},
"type": {
"$ref": "#\/components\/schemas\/BackupJobType"
},
"status": {
"description": "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.",
"$ref": "#\/components\/schemas\/BackupJobStatus"
},
"status_label": {
"type": "string",
"description": "The status as the Backup Chief app shows it, naming the next step while the job is pending.",
"examples": [
"Save recovery document"
]
},
"provisioning_state": {
"description": "The step the storage setup reached.",
"$ref": "#\/components\/schemas\/BackupJobProvisioningState"
},
"provisioning_error_code": {
"anyOf": [
{
"description": "Why the storage setup stopped, null while it is fine. Retry with the retry-provisioning endpoint once the cause is fixed.",
"$ref": "#\/components\/schemas\/BackupJobProvisioningErrorCode"
},
{
"type": "null"
}
]
},
"recovery_document": {
"anyOf": [
{
"description": "State of the recovery document, which is created, downloaded and confirmed in the Backup Chief app only. Null before storage setup creates it.",
"$ref": "#\/components\/schemas\/BackupJobRecoveryState"
},
{
"type": "null"
}
]
},
"server": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted server ID.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"storage_destination": {
"type": "object",
"description": "The storage destination that keeps the main copy.",
"properties": {
"id": {
"type": "string",
"description": "Formatted storage destination ID.",
"examples": [
"storage_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"source_summary": {
"type": "string",
"description": "One line describing what the job backs up.",
"examples": [
"\/var\/www"
]
},
"source": {
"description": "What the job backs up: FileBackupSource for file, MySqlBackupSource for mysql, PostgreSqlBackupSource for postgresql. Passwords are never returned.",
"anyOf": [
{
"$ref": "#\/components\/schemas\/FileBackupSource"
},
{
"$ref": "#\/components\/schemas\/MySqlBackupSource"
},
{
"$ref": "#\/components\/schemas\/PostgreSqlBackupSource"
}
]
},
"schedule": {
"type": "object",
"properties": {
"kind": {
"$ref": "#\/components\/schemas\/BackupJobScheduleKind"
},
"preset": {
"anyOf": [
{
"$ref": "#\/components\/schemas\/BackupJobSchedulePreset"
},
{
"type": "null"
}
]
},
"label": {
"type": "string",
"description": "The schedule in words.",
"examples": [
"Every day"
]
},
"start_time": {
"type": [
"string",
"null"
],
"description": "Local time in the team's timezone at which a preset schedule starts, null for cron schedules.",
"examples": [
"02:00"
]
},
"cron": {
"type": "string",
"description": "Cron expression the schedule runs on, in the schedule timezone.",
"examples": [
"0 2 * * *"
]
},
"timezone": {
"type": "string",
"examples": [
"UTC"
]
},
"next_run_at": {
"type": [
"string",
"null"
],
"description": "When the job runs next, null unless it is active."
}
},
"required": [
"kind",
"preset",
"label",
"start_time",
"cron",
"timezone",
"next_run_at"
]
},
"retention": {
"type": "object",
"description": "How many backups are kept.",
"properties": {
"last": {
"type": "integer"
},
"hourly": {
"type": "integer"
},
"daily": {
"type": "integer"
},
"weekly": {
"type": "integer"
},
"monthly": {
"type": "integer"
},
"yearly": {
"type": "integer"
}
},
"required": [
"last",
"hourly",
"daily",
"weekly",
"monthly",
"yearly"
]
},
"retention_label": {
"type": "string",
"description": "The keep policy in words.",
"examples": [
"Keeps the last 12 backups, 7 daily and 4 weekly."
]
},
"integrity": {
"type": "object",
"description": "When the agent checks the repository, as cron expressions in UTC.",
"properties": {
"metadata_cron": {
"type": "string",
"description": "Check of the repository structure."
},
"data_mode": {
"description": "How the stored data is read back. auto reads one of data_parts parts at each data check, so all data is read over a full cycle.",
"$ref": "#\/components\/schemas\/BackupJobIntegrityDataMode"
},
"data_cron": {
"type": "string"
},
"data_parts": {
"type": "integer",
"description": "Number of parts the data check reads one of at a time."
}
},
"required": [
"metadata_cron",
"data_mode",
"data_cron",
"data_parts"
]
},
"repository_bytes": {
"type": [
"integer",
"null"
],
"description": "Bytes the main repository last reported, null until it was measured."
},
"last_run_at": {
"type": [
"string",
"null"
]
},
"last_full_success_at": {
"type": [
"string",
"null"
]
},
"paused_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"type",
"status",
"status_label",
"provisioning_state",
"provisioning_error_code",
"recovery_document",
"server",
"storage_destination",
"source_summary",
"source",
"schedule",
"retention",
"retention_label",
"integrity",
"repository_bytes",
"last_run_at",
"last_full_success_at",
"paused_at",
"created_at"
],
"title": "BackupJob"
},
"BackupJobIntegrityDataMode": {
"type": "string",
"description": "How the data integrity checks of a backup job are scheduled: auto spreads the checks over the retention period.\n",
"x-extensible-enum": [
"auto"
],
"title": "BackupJobIntegrityDataMode"
},
"BackupJobProvisioningErrorCode": {
"type": "string",
"description": "Why the storage setup of a backup job stopped.\n",
"x-extensible-enum": [
"provisioning_failed",
"provisioning_timed_out",
"repository_missing",
"repository_conflict",
"repository_identity_changed",
"invalid_key_replacement",
"recovery_key_missing",
"replica_provisioning_failed",
"replica_copy_failed",
"replica_inventory_incomplete"
],
"title": "BackupJobProvisioningErrorCode"
},
"BackupJobProvisioningState": {
"type": "string",
"x-extensible-enum": [
"reserved",
"repository_missing",
"initializing_repository",
"repository_initialized",
"service_key_recorded",
"recovery_key_missing",
"adding_recovery_key",
"recovery_key_added",
"recovery_key_verified",
"recovery_key_recorded",
"removing_previous_key",
"previous_key_removal_reported",
"awaiting_acknowledgement",
"awaiting_copy",
"copying_snapshots",
"verifying_snapshots",
"complete",
"repository_conflict"
],
"title": "BackupJobProvisioningState"
},
"BackupJobRecoveryState": {
"type": "string",
"x-extensible-enum": [
"preparing",
"ready",
"revealed",
"expired",
"replacing",
"confirmed"
],
"title": "BackupJobRecoveryState"
},
"BackupJobScheduleKind": {
"type": "string",
"x-extensible-enum": [
"preset",
"cron"
],
"title": "BackupJobScheduleKind"
},
"BackupJobSchedulePreset": {
"type": "string",
"x-extensible-enum": [
"m5",
"m6",
"m10",
"m15",
"m20",
"m30",
"h1",
"h2",
"h3",
"h4",
"h6",
"h12",
"h24"
],
"title": "BackupJobSchedulePreset"
},
"BackupJobStatus": {
"type": "string",
"x-extensible-enum": [
"pending",
"active",
"paused",
"deleting"
],
"title": "BackupJobStatus"
},
"BackupJobType": {
"type": "string",
"x-extensible-enum": [
"file",
"mysql",
"postgresql"
],
"title": "BackupJobType"
},
"BackupRepository": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted repository ID.",
"examples": [
"repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"role": {
"description": "main for the repository backups are written to, extra_copy for a copy of it at another storage destination.",
"$ref": "#\/components\/schemas\/BackupRepositoryRole"
},
"storage_destination": {
"type": [
"object",
"null"
],
"description": "The storage destination that keeps the repository, null when it was deleted.",
"properties": {
"id": {
"type": "string",
"description": "Formatted storage destination ID.",
"examples": [
"storage_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"status": {
"$ref": "#\/components\/schemas\/BackupRepositoryStatus"
},
"provisioning_state": {
"$ref": "#\/components\/schemas\/BackupJobProvisioningState"
},
"healthy": {
"type": "boolean",
"description": "Whether the repository is active."
},
"repository_bytes": {
"type": [
"integer",
"null"
],
"description": "Bytes the repository last reported, null until it was measured."
},
"initial_sync_completed_at": {
"type": [
"string",
"null"
]
},
"last_copy_at": {
"type": [
"string",
"null"
],
"description": "When backups were last copied to an extra copy."
},
"last_check_at": {
"type": [
"string",
"null"
]
},
"detached_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"role",
"storage_destination",
"status",
"provisioning_state",
"healthy",
"repository_bytes",
"initial_sync_completed_at",
"last_copy_at",
"last_check_at",
"detached_at"
],
"title": "BackupRepository"
},
"BackupRepositoryRole": {
"type": "string",
"description": "The role of a repository of a backup job: the main repository backups are written to, or an extra copy.\n",
"x-extensible-enum": [
"main",
"extra_copy"
],
"title": "BackupRepositoryRole"
},
"BackupRepositoryStatus": {
"type": "string",
"x-extensible-enum": [
"provisioning",
"active",
"failed",
"detached"
],
"title": "BackupRepositoryStatus"
},
"BackupRun": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted run ID.",
"examples": [
"run_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted backup job ID.",
"examples": [
"job_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"server": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted server ID.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"kind": {
"description": "backup for a backup, or the maintenance operation the run performed.",
"$ref": "#\/components\/schemas\/BackupRunKind"
},
"trigger": {
"description": "manual for a run someone started, scheduled for a run the schedule started.",
"$ref": "#\/components\/schemas\/BackupRunTrigger"
},
"status": {
"description": "The state of the run as the agent reported it.",
"$ref": "#\/components\/schemas\/BackupRunStatus"
},
"status_label": {
"type": "string",
"description": "The outcome as the Backup Chief app shows it, which also accounts for extra copies that failed.",
"examples": [
"Succeeded"
]
},
"result_code": {
"anyOf": [
{
"description": "Why the run ended the way it did, null while it runs.",
"$ref": "#\/components\/schemas\/BackupRunResultCode"
},
{
"type": "null"
}
]
},
"summary": {
"type": [
"string",
"null"
],
"description": "Short summary the agent reported."
},
"source_files": {
"description": "Files the backup read, null for maintenance runs and until reported."
},
"source_bytes": {
"description": "Bytes the backup read, null for maintenance runs and until reported."
},
"stored_bytes": {
"description": "New bytes the backup added to the repository after deduplication, null for maintenance runs and until reported."
},
"statistics": {
"type": "array",
"description": "The reported figures as the Backup Chief app shows them.",
"examples": [
[
"1,204 files",
"2.3 GB processed",
"+12 MB added"
]
],
"items": {
"type": "string"
}
},
"repository_bytes": {
"type": [
"integer",
"null"
],
"description": "Size of the main repository after the run, null until reported."
},
"repository_bytes_delta": {
"type": [
"integer",
"null"
],
"description": "How much the main repository grew or shrank, null until reported."
},
"snapshots_count": {
"type": "string",
"description": "Snapshots the backup made: one for a file backup, one per database for a database backup."
},
"available_snapshots_count": {
"type": "string",
"description": "Snapshots that can still be restored."
},
"restorable": {
"type": "boolean",
"description": "Whether the run is a recovery point whose snapshots can all still be restored."
},
"kept_forever_at": {
"type": [
"string",
"null"
],
"description": "When the recovery point was set to be kept forever, null when the job's retention policy applies."
},
"has_log": {
"type": "boolean",
"description": "Whether a complete log of the run can be read from the log endpoint."
},
"repositories": {
"type": "array",
"description": "The result per repository: the main repository and each extra copy the run wrote to or copied to.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted repository ID.",
"examples": [
"repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"storage_destination": {
"type": [
"object",
"null"
],
"description": "The storage destination that keeps the repository, null when it was deleted.",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"status": {
"$ref": "#\/components\/schemas\/BackupRunStatus"
},
"result_code": {
"$ref": "#\/components\/schemas\/BackupRunResultCode"
},
"summary": {
"type": [
"string",
"null"
]
},
"diagnostic": {
"type": [
"string",
"null"
],
"description": "Technical detail about a failure, as the agent reported it."
},
"attempt_count": {
"type": "integer"
},
"repository_bytes": {
"type": [
"integer",
"null"
]
},
"started_at": {
"type": "string"
},
"finished_at": {
"type": "string"
}
},
"required": [
"id",
"storage_destination",
"status",
"result_code",
"summary",
"diagnostic",
"attempt_count",
"repository_bytes",
"started_at",
"finished_at"
]
}
},
"scheduled_for": {
"type": [
"string",
"null"
],
"description": "The minute a scheduled run was due, null for manual runs."
},
"started_at": {
"type": [
"string",
"null"
]
},
"finished_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"job",
"server",
"kind",
"trigger",
"status",
"status_label",
"result_code",
"summary",
"source_files",
"source_bytes",
"stored_bytes",
"statistics",
"repository_bytes",
"repository_bytes_delta",
"snapshots_count",
"available_snapshots_count",
"restorable",
"kept_forever_at",
"has_log",
"repositories",
"scheduled_for",
"started_at",
"finished_at",
"created_at"
],
"title": "BackupRun"
},
"BackupRunKind": {
"type": "string",
"x-extensible-enum": [
"backup",
"forget",
"prune",
"check_metadata",
"check_data",
"snapshot_inventory"
],
"title": "BackupRunKind"
},
"BackupRunResultCode": {
"type": "string",
"x-extensible-enum": [
"success",
"empty_selection",
"unreadable_files",
"databases_failed",
"tool_unavailable",
"source_authentication_failed",
"database_selection_invalid",
"invalid_root",
"repository_locked",
"repository_authentication_failed",
"timed_out",
"execution_failed",
"cancelled",
"expired",
"config_unavailable",
"schedule_overlap",
"outcome_unresolved",
"recovery_point_unavailable",
"unresolved_runs_present",
"repository_missing",
"repository_corrupt",
"snapshot_removal_incomplete",
"recovery_point_protected",
"repository_operations_incomplete",
"replicas_not_synchronized"
],
"title": "BackupRunResultCode"
},
"BackupRunStatus": {
"type": "string",
"x-extensible-enum": [
"pending",
"running",
"complete",
"partial",
"failed",
"cancelled",
"skipped",
"unresolved"
],
"title": "BackupRunStatus"
},
"BackupRunTrigger": {
"type": "string",
"description": "What started a run: a person or API call, or the schedule.\n",
"x-extensible-enum": [
"manual",
"scheduled"
],
"title": "BackupRunTrigger"
},
"CreateDownloadRequest": {
"type": "object",
"properties": {
"snapshot": {
"type": "string",
"description": "Formatted ID of the snapshot to download from, as listed by the job's snapshots.",
"examples": [
"snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"path": {
"type": [
"string",
"null"
],
"description": "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.",
"examples": [
"\/var\/www\/shop\/storage\/invoices"
],
"maxLength": 4096
},
"path_type": {
"type": [
"string",
"null"
],
"description": "For a file backup: whether the path is a file or a directory.",
"enum": [
"file",
"directory",
null
]
},
"repository": {
"type": [
"string",
"null"
],
"description": "Formatted ID of the repository to read from, the main repository when left out. Use it to download from an extra copy.",
"examples": [
"repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
}
},
"required": [
"snapshot"
],
"title": "CreateDownloadRequest"
},
"DatabaseSelectionMode": {
"type": "string",
"description": "Which databases a database backup job backs up: every database the user can read, the listed databases, or all but the listed databases.\n",
"x-extensible-enum": [
"all_accessible",
"selected",
"exclude"
],
"title": "DatabaseSelectionMode"
},
"DatabaseTableSelectionMode": {
"type": "string",
"description": "Which tables a database backup job backs up: all tables, only the listed tables, or all but the listed tables.\n",
"x-extensible-enum": [
"all",
"include",
"exclude"
],
"title": "DatabaseTableSelectionMode"
},
"Download": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted download ID.",
"examples": [
"download_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted backup job ID.",
"examples": [
"job_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"snapshot_id": {
"type": "string",
"description": "Formatted ID of the snapshot the download is made from.",
"examples": [
"snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"run_id": {
"type": "string",
"description": "Formatted ID of the backup run that made the snapshot.",
"examples": [
"run_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"repository": {
"type": [
"object",
"null"
],
"description": "The repository the download is read from, null for downloads that predate extra copies.",
"properties": {
"id": {
"type": "string",
"description": "Formatted repository ID.",
"examples": [
"repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"storage_destination": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
},
"required": [
"id",
"storage_destination"
]
},
"kind": {
"description": "file or directory for a file backup, database for a database dump.",
"$ref": "#\/components\/schemas\/DownloadKind"
},
"name": {
"type": "string",
"description": "File name of the ZIP.",
"examples": [
"invoices-4f2a9c1d.zip"
]
},
"status": {
"description": "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.",
"$ref": "#\/components\/schemas\/DownloadStatus"
},
"status_label": {
"type": "string",
"description": "The status as the Backup Chief app shows it.",
"enum": [
"Queued",
"Checking size",
"Preparing ZIP",
"Ready",
"Deleting",
"Failed",
"Cancelled",
"Expired"
],
"examples": [
"Preparing ZIP"
]
},
"downloadable": {
"type": "boolean",
"description": "Whether the ZIP can be downloaded now: create a download URL for it."
},
"source_bytes": {
"type": [
"integer",
"null"
],
"description": "Bytes of backup data the download contains, null until checked."
},
"archive_bytes": {
"type": [
"integer",
"null"
],
"description": "Size of the ZIP, null until it is ready."
},
"uploaded_bytes": {
"type": "integer",
"description": "Bytes of the ZIP uploaded so far while it is prepared."
},
"sha256": {
"type": [
"string",
"null"
],
"description": "SHA-256 checksum of the ZIP, null until it is ready."
},
"failure_code": {
"anyOf": [
{
"description": "Why the download failed, null unless it failed.",
"$ref": "#\/components\/schemas\/DownloadFailureCode"
},
{
"type": "null"
}
]
},
"failure_message": {
"type": [
"string",
"null"
],
"description": "The failure explained, null unless it failed."
},
"download_count": {
"type": "integer",
"description": "How often the ZIP was downloaded."
},
"requested_by": {
"type": [
"string",
"null"
],
"description": "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": {
"type": "string"
},
"started_at": {
"type": [
"string",
"null"
]
},
"ready_at": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When the ZIP is deleted, or was deleted."
},
"last_downloaded_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"job",
"snapshot_id",
"run_id",
"repository",
"kind",
"name",
"status",
"status_label",
"downloadable",
"source_bytes",
"archive_bytes",
"uploaded_bytes",
"sha256",
"failure_code",
"failure_message",
"download_count",
"requested_by",
"created_at",
"started_at",
"ready_at",
"expires_at",
"last_downloaded_at"
],
"title": "Download"
},
"DownloadFailureCode": {
"type": "string",
"description": "Why a download could not be prepared.\n",
"x-extensible-enum": [
"source_too_large",
"archive_too_large",
"source_unavailable",
"cancelled",
"operation_timeout",
"invalid_archive",
"empty_archive",
"invalid_inspection",
"artifact_storage_failed",
"artifact_storage_unavailable",
"artifact_size_mismatch"
],
"title": "DownloadFailureCode"
},
"DownloadKind": {
"type": "string",
"x-extensible-enum": [
"file",
"directory",
"database"
],
"title": "DownloadKind"
},
"DownloadStatus": {
"type": "string",
"x-extensible-enum": [
"queued",
"inspecting",
"preparing",
"ready",
"expiring",
"failed",
"cancelled",
"expired"
],
"title": "DownloadStatus"
},
"FileBackupSource": {
"type": "object",
"properties": {
"paths": {
"type": "array",
"description": "Directories that are backed up.",
"items": {
"type": "string"
}
},
"excludes": {
"type": "array",
"description": "Files and folders that are skipped.",
"items": {
"type": "string"
}
}
},
"required": [
"paths",
"excludes"
],
"title": "FileBackupSource"
},
"InspectSourceRequest": {
"type": "object",
"description": "Validates a source to test, for a new backup job on a server or for a change to an existing job.",
"properties": {
"job": {
"type": "string",
"description": "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.",
"examples": [
"job_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"server": {
"type": "string",
"description": "Formatted ID of the enrolled server that tests the source of a new job.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"type": {
"type": "string",
"description": "The type of the new job.",
"enum": [
"file",
"mysql",
"postgresql"
]
},
"source": {
"type": "object",
"description": "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.",
"properties": {
"paths": {
"type": "array",
"description": "file: absolute directories to back up, at most 100.",
"examples": [
[
"\/var\/www"
]
],
"items": {
"type": "string"
}
},
"excludes": {
"type": "array",
"description": "file: files and folders to skip, as restic exclude patterns, at most 100.",
"examples": [
[
"*.log",
"storage\/cache"
]
],
"items": {
"type": "string"
}
},
"host": {
"type": "string",
"description": "mysql, postgresql: database server host.",
"examples": [
"127.0.0.1"
]
},
"port": {
"type": "integer",
"description": "mysql, postgresql: database server port.",
"examples": [
3306
]
},
"username": {
"type": "string",
"description": "mysql, postgresql: user the agent signs in as."
},
"password": {
"type": [
"string",
"null"
],
"description": "mysql, postgresql: password of the user. It is stored encrypted and never returned; leave it out to keep the stored password."
},
"password_file": {
"type": [
"string",
"null"
],
"description": "mysql, postgresql: absolute path of a file on the server that holds the password, or null to stop using one."
},
"no_password": {
"type": "boolean",
"description": "mysql, postgresql: true when the user signs in without a password."
},
"connection_database": {
"type": "string",
"description": "postgresql: database to connect to for listing the other databases."
},
"selection_mode": {
"type": "string",
"description": "mysql, postgresql: all_accessible for every database the user can read, selected for the listed databases, exclude for all but the listed databases.",
"enum": [
"all_accessible",
"selected",
"exclude"
]
},
"databases": {
"type": "array",
"description": "mysql, postgresql: databases for the selected and exclude modes.",
"items": {
"type": "string"
}
},
"include_routines": {
"type": "boolean",
"description": "mysql: also back up stored routines."
},
"include_events": {
"type": "boolean",
"description": "mysql: also back up scheduled events."
},
"custom_flags": {
"type": "array",
"description": "mysql: extra mysqldump long options.",
"examples": [
[
"--hex-blob"
]
],
"items": {
"type": "string"
}
},
"table_selection": {
"type": "object",
"description": "mysql, postgresql: limit the tables: mode all, include or exclude, with tables naming a database and table (and schema for postgresql).",
"properties": {
"mode": {
"type": "string",
"description": "Which tables a database backup job backs up: all tables, only the listed tables, or all but the listed tables.\n",
"enum": [
"all",
"include",
"exclude"
]
},
"tables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"database": {
"type": "string"
},
"schema": {
"type": "string"
},
"table": {
"type": "string"
}
}
}
}
}
}
}
}
},
"required": [
"source"
],
"title": "InspectSourceRequest"
},
"LocalStorageSettings": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path relative to the application's storage directory."
}
},
"required": [
"path"
],
"title": "LocalStorageSettings"
},
"MySqlBackupSource": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "integer"
},
"username": {
"type": "string"
},
"password_set": {
"type": "boolean",
"description": "Whether a password is stored. It is never returned."
},
"password_file": {
"type": [
"string",
"null"
]
},
"selection_mode": {
"$ref": "#\/components\/schemas\/DatabaseSelectionMode"
},
"databases": {
"type": "array",
"items": {
"type": "string"
}
},
"include_routines": {
"type": "boolean"
},
"include_events": {
"type": "boolean"
},
"custom_flags": {
"type": "array",
"items": {
"type": "string"
}
},
"table_selection": {
"type": [
"object",
"null"
],
"description": "The tables the job is limited to, null for all tables.",
"properties": {
"mode": {
"$ref": "#\/components\/schemas\/DatabaseTableSelectionMode"
},
"tables": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"required": [
"mode",
"tables"
]
}
},
"required": [
"host",
"port",
"username",
"password_set",
"password_file",
"selection_mode",
"databases",
"include_routines",
"include_events",
"custom_flags",
"table_selection"
],
"title": "MySqlBackupSource"
},
"PostgreSqlBackupSource": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "integer"
},
"username": {
"type": "string"
},
"password_set": {
"type": "boolean",
"description": "Whether a password is stored. It is never returned."
},
"password_file": {
"type": [
"string",
"null"
]
},
"connection_database": {
"type": "string"
},
"selection_mode": {
"$ref": "#\/components\/schemas\/DatabaseSelectionMode"
},
"databases": {
"type": "array",
"items": {
"type": "string"
}
},
"table_selection": {
"type": [
"object",
"null"
],
"description": "The tables the job is limited to, null for all tables.",
"properties": {
"mode": {
"$ref": "#\/components\/schemas\/DatabaseTableSelectionMode"
},
"tables": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"required": [
"mode",
"tables"
]
}
},
"required": [
"host",
"port",
"username",
"password_set",
"password_file",
"connection_database",
"selection_mode",
"databases",
"table_selection"
],
"title": "PostgreSqlBackupSource"
},
"QueueMaintenanceRequest": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "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": [
"forget",
"prune",
"snapshot_inventory"
]
}
},
"required": [
"operation"
],
"title": "QueueMaintenanceRequest"
},
"S3StorageSettings": {
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"examples": [
"https:\/\/s3.eu-central-1.amazonaws.com"
]
},
"region": {
"type": "string",
"examples": [
"eu-central-1"
]
},
"bucket": {
"type": "string",
"examples": [
"backups"
]
},
"root_path": {
"type": "string",
"description": "Path inside the bucket that holds the repositories.",
"examples": [
"backupchief"
]
}
},
"required": [
"endpoint",
"region",
"bucket",
"root_path"
],
"title": "S3StorageSettings"
},
"SaveBackupJobRequest": {
"type": "object",
"description": "Validates a backup job and turns its source into the configuration of its type, the same way the job forms do.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the backup job.",
"examples": [
"Website files"
],
"maxLength": 255
},
"server": {
"type": "string",
"description": "Formatted ID of the enrolled server that runs the job. It cannot be changed later.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"storage_destination": {
"type": "string",
"description": "Formatted ID of the storage destination that keeps the main copy. It cannot be changed later.",
"examples": [
"storage_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"type": {
"type": "string",
"description": "What the job backs up. It cannot be changed later.",
"enum": [
"file",
"mysql",
"postgresql"
]
},
"source": {
"type": "object",
"description": "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.",
"properties": {
"paths": {
"type": "array",
"description": "file: absolute directories to back up, at most 100.",
"examples": [
[
"\/var\/www"
]
],
"items": {
"type": "string"
}
},
"excludes": {
"type": "array",
"description": "file: files and folders to skip, as restic exclude patterns, at most 100.",
"examples": [
[
"*.log",
"storage\/cache"
]
],
"items": {
"type": "string"
}
},
"host": {
"type": "string",
"description": "mysql, postgresql: database server host.",
"examples": [
"127.0.0.1"
]
},
"port": {
"type": "integer",
"description": "mysql, postgresql: database server port.",
"examples": [
3306
]
},
"username": {
"type": "string",
"description": "mysql, postgresql: user the agent signs in as."
},
"password": {
"type": [
"string",
"null"
],
"description": "mysql, postgresql: password of the user. It is stored encrypted and never returned; leave it out to keep the stored password."
},
"password_file": {
"type": [
"string",
"null"
],
"description": "mysql, postgresql: absolute path of a file on the server that holds the password, or null to stop using one."
},
"no_password": {
"type": "boolean",
"description": "mysql, postgresql: true when the user signs in without a password."
},
"connection_database": {
"type": "string",
"description": "postgresql: database to connect to for listing the other databases."
},
"selection_mode": {
"type": "string",
"description": "mysql, postgresql: all_accessible for every database the user can read, selected for the listed databases, exclude for all but the listed databases.",
"enum": [
"all_accessible",
"selected",
"exclude"
]
},
"databases": {
"type": "array",
"description": "mysql, postgresql: databases for the selected and exclude modes.",
"items": {
"type": "string"
}
},
"include_routines": {
"type": "boolean",
"description": "mysql: also back up stored routines."
},
"include_events": {
"type": "boolean",
"description": "mysql: also back up scheduled events."
},
"custom_flags": {
"type": "array",
"description": "mysql: extra mysqldump long options.",
"examples": [
[
"--hex-blob"
]
],
"items": {
"type": "string"
}
},
"table_selection": {
"type": "object",
"description": "mysql, postgresql: limit the tables: mode all, include or exclude, with tables naming a database and table (and schema for postgresql).",
"properties": {
"mode": {
"type": "string",
"description": "Which tables a database backup job backs up: all tables, only the listed tables, or all but the listed tables.\n",
"enum": [
"all",
"include",
"exclude"
]
},
"tables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"database": {
"type": "string"
},
"schema": {
"type": "string"
},
"table": {
"type": "string"
}
}
}
}
}
}
}
},
"source_inspection": {
"type": [
"string",
"null"
],
"description": "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.",
"examples": [
"inspection_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"schedule": {
"type": "object",
"description": "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.",
"properties": {
"kind": {
"type": "string",
"description": "preset to run at a fixed interval from a start time, cron for a cron expression in UTC.",
"enum": [
"preset",
"cron"
]
},
"preset": {
"type": [
"string",
"null"
],
"description": "The interval of a preset schedule.",
"enum": [
"m5",
"m6",
"m10",
"m15",
"m20",
"m30",
"h1",
"h2",
"h3",
"h4",
"h6",
"h12",
"h24",
null
]
},
"start_time": {
"type": [
"string",
"null"
],
"description": "Local time in the team's timezone at which a preset schedule starts, in 24-hour HH:MM. Defaults to the current start time of the job, or the next full hour.",
"examples": [
"02:00"
]
},
"cron": {
"type": [
"string",
"null"
],
"description": "Five-field cron expression in UTC for a cron schedule.",
"examples": [
"30 2 * * *"
],
"maxLength": 100
}
}
},
"retention": {
"type": "object",
"description": "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.",
"properties": {
"last": {
"type": "integer",
"description": "The most recent backups to keep, whatever their age.",
"minimum": 0,
"maximum": 8760
},
"hourly": {
"type": "integer",
"description": "One backup for each of this many most recent hours.",
"minimum": 0,
"maximum": 8760
},
"daily": {
"type": "integer",
"description": "One backup for each of this many most recent days.",
"minimum": 0,
"maximum": 3660
},
"weekly": {
"type": "integer",
"description": "One backup for each of this many most recent weeks.",
"minimum": 0,
"maximum": 520
},
"monthly": {
"type": "integer",
"description": "One backup for each of this many most recent months.",
"minimum": 0,
"maximum": 120
},
"yearly": {
"type": "integer",
"description": "One backup for each of this many most recent years.",
"minimum": 0,
"maximum": 100
}
}
},
"attempt_id": {
"type": "string",
"description": "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.",
"examples": [
"01j8q8zk2f4m6n7p9r1s3t5v7x"
]
}
},
"required": [
"name",
"server",
"storage_destination",
"type",
"source"
],
"title": "SaveBackupJobRequest"
},
"SaveServerRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name of the server.",
"examples": [
"Web server"
],
"maxLength": 255
},
"agent_auto_updates": {
"type": [
"boolean",
"null"
],
"description": "Whether the server installs new agent releases automatically, null to follow the team setting."
}
},
"required": [
"name"
],
"title": "SaveServerRequest"
},
"SaveStorageDestinationRequest": {
"type": "object",
"description": "Validates the settings of a storage destination and turns them into the driver form state the storage services take.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the destination, unique within the team.",
"examples": [
"Production S3"
],
"maxLength": 255
},
"driver": {
"type": "string",
"description": "Storage driver. local is only available in development.",
"enum": [
"s3",
"sftp"
],
"examples": [
"s3"
]
},
"settings": {
"type": "object",
"description": "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.",
"properties": {
"endpoint": {
"type": [
"string",
"null"
],
"description": "S3: endpoint URL of the S3-compatible service, HTTPS on port 443.",
"examples": [
"https:\/\/s3.eu-central-1.amazonaws.com"
]
},
"region": {
"type": [
"string",
"null"
],
"description": "S3: region of the bucket.",
"examples": [
"eu-central-1"
]
},
"bucket": {
"type": [
"string",
"null"
],
"description": "S3: bucket name.",
"examples": [
"backups"
]
},
"root_path": {
"type": [
"string",
"null"
],
"description": "S3 and SFTP: path that holds the repositories, inside the bucket or on the SFTP server.",
"examples": [
"backupchief"
]
},
"access_key_id": {
"type": [
"string",
"null"
],
"description": "S3: access key ID. Required to create, leave out to keep the current one. Never returned."
},
"secret_access_key": {
"type": [
"string",
"null"
],
"description": "S3: secret access key. Required to create, leave out to keep the current one. Never returned."
},
"host": {
"type": [
"string",
"null"
],
"description": "SFTP: hostname or IP address of the server.",
"examples": [
"storage.example.com"
]
},
"port": {
"type": [
"integer",
"null"
],
"description": "SFTP: port of the server.",
"default": 22
},
"username": {
"type": [
"string",
"null"
],
"description": "SFTP: username to sign in with.",
"examples": [
"backup"
]
},
"password": {
"type": [
"string",
"null"
],
"description": "SFTP: password to sign in with. Required to create, leave out to keep the current one. Never returned."
},
"reset_host_keys": {
"type": "boolean",
"description": "SFTP: forget the pinned host keys and pin the keys the server presents at the next access check, after a host key change."
},
"path": {
"type": [
"string",
"null"
],
"description": "Local: path relative to the application's storage directory, development only.",
"examples": [
"backups\/local"
]
}
}
}
},
"required": [
"name",
"driver",
"settings"
],
"title": "SaveStorageDestinationRequest"
},
"Server": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted server ID.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string",
"examples": [
"Web server"
]
},
"hostname": {
"type": [
"string",
"null"
],
"description": "Hostname the agent reported, null until it enrolls.",
"examples": [
"web-1.example.com"
]
},
"status": {
"description": "pending until an agent enrolls with an enrollment token, enrolled while an agent is set up, revoked once its agent was revoked.",
"$ref": "#\/components\/schemas\/ServerStatus"
},
"connected": {
"type": "boolean",
"description": "Whether the server is enrolled and its agent reported within the last few minutes."
},
"platform": {
"type": [
"string",
"null"
],
"description": "Operating system and CPU architecture the agent reported.",
"examples": [
"linux\/amd64"
]
},
"agent": {
"type": "object",
"properties": {
"version": {
"type": [
"string",
"null"
],
"description": "Version of the installed agent, null until it enrolls.",
"examples": [
"1.4.2"
]
},
"auto_updates": {
"type": "boolean",
"description": "Whether the server installs new agent releases automatically, following the team setting unless the server overrides it."
},
"auto_updates_override": {
"type": [
"boolean",
"null"
],
"description": "The server's own automatic update setting, null when it follows the team setting."
},
"upgrade_required": {
"type": "boolean",
"description": "Whether the agent must be updated by hand before it can run backups again."
},
"update": {
"type": [
"object",
"null"
],
"description": "The latest agent update requested for the server, null when none was requested.",
"properties": {
"target_version": {
"description": "Agent version the update installs.",
"examples": [
"1.5.0"
]
},
"status": {
"description": "pending until the agent picks it up, acknowledged while it installs, then completed, cancelled or expired. Whether a completed update succeeded shows in the agent version.",
"$ref": "#\/components\/schemas\/AgentCommandStatus"
},
"requested_at": {
"type": "string"
},
"completed_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"target_version",
"status",
"requested_at",
"completed_at"
]
}
},
"required": [
"version",
"auto_updates",
"auto_updates_override",
"upgrade_required",
"update"
]
},
"active_jobs_count": {
"type": "integer",
"description": "Number of active backup jobs on the server."
},
"jobs_count": {
"type": "integer",
"description": "Number of backup jobs on the server, including paused ones."
},
"last_contact_at": {
"type": [
"string",
"null"
],
"description": "When the agent last contacted Backup Chief."
},
"enrolled_at": {
"type": [
"string",
"null"
]
},
"revoked_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"enrollment": {
"type": "object",
"description": "The one-time enrollment token, only included in the response that issued it.",
"properties": {
"token": {
"type": "string",
"description": "One-time enrollment token. It is only returned once: run the setup command right away or issue a new token.",
"examples": [
"bcenr_4Jd8sKq2LmN7pR1tV5xZ9bC3fG6hJ0kM8nQ2wE"
]
},
"setup_command": {
"type": "string",
"description": "Shell command that installs the agent and enrolls it with the token, run it as root on the server."
},
"expires_at": {
"type": "string",
"description": "When the token can no longer be used."
}
},
"required": [
"token",
"setup_command",
"expires_at"
]
}
},
"required": [
"id",
"name",
"hostname",
"status",
"connected",
"platform",
"agent",
"last_contact_at",
"enrolled_at",
"revoked_at",
"created_at"
],
"title": "Server"
},
"ServerStatus": {
"type": "string",
"description": "The enrollment status of a server: pending until an agent enrolls, enrolled while an agent is set up, revoked once its agent was revoked.\n",
"x-extensible-enum": [
"pending",
"enrolled",
"revoked"
],
"title": "ServerStatus"
},
"SftpAuthMethod": {
"type": "string",
"description": "How an SFTP storage destination signs in: a password, or an Ed25519 key generated in the Backup Chief app.\n",
"x-extensible-enum": [
"password",
"ed25519"
],
"title": "SftpAuthMethod"
},
"SftpStorageSettings": {
"type": "object",
"properties": {
"host": {
"type": "string",
"examples": [
"storage.example.com"
]
},
"port": {
"type": "integer",
"examples": [
22
]
},
"username": {
"type": "string",
"examples": [
"backup"
]
},
"root_path": {
"type": "string",
"examples": [
"\/backupchief"
]
},
"auth_method": {
"description": "password, or ed25519 for a key generated in Backup Chief.",
"$ref": "#\/components\/schemas\/SftpAuthMethod"
},
"public_key": {
"type": [
"string",
"null"
],
"description": "Public key to authorize on the SFTP server, null for password authentication."
},
"fingerprint": {
"type": [
"string",
"null"
],
"description": "Fingerprint of the public key, null for password authentication."
},
"host_keys": {
"type": "array",
"description": "Host keys of the SFTP server pinned at the first connection. Connections presenting another key are refused.",
"items": {
"type": "string"
}
}
},
"required": [
"host",
"port",
"username",
"root_path",
"auth_method",
"public_key",
"fingerprint",
"host_keys"
],
"title": "SftpStorageSettings"
},
"Snapshot": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted snapshot ID.",
"examples": [
"snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"snapshot_id": {
"type": "string",
"description": "The restic snapshot ID in the repository the backup wrote to.",
"examples": [
"4f2a9c1d8e7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f"
]
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted backup job ID.",
"examples": [
"job_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"run_id": {
"type": "string",
"description": "Formatted ID of the backup run that made the snapshot. Keeping forever and expiring work on this run, the recovery point.",
"examples": [
"run_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"availability": {
"description": "Whether the snapshot can still be restored from the repository the backup wrote to.",
"$ref": "#\/components\/schemas\/SnapshotAvailability"
},
"source_bytes": {
"type": [
"integer",
"null"
],
"description": "Bytes the backup read for this snapshot."
},
"stored_bytes": {
"type": [
"integer",
"null"
],
"description": "New bytes this snapshot added to the repository after deduplication."
},
"database": {
"type": [
"object",
"null"
],
"description": "The database of a database backup snapshot, null for file backups.",
"properties": {
"name": {
"examples": [
"shop"
]
},
"filename": {
"examples": [
"shop.sql"
]
}
},
"required": [
"name",
"filename"
]
},
"kept_forever_at": {
"type": [
"string",
"null"
],
"description": "When the recovery point was set to be kept forever, null when the job's retention policy applies."
},
"copies": {
"type": "array",
"description": "The copies of the snapshot in extra copy repositories.",
"items": {
"type": "object",
"properties": {
"repository_id": {
"type": "string",
"description": "Formatted repository ID.",
"examples": [
"repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"storage_destination": {
"type": [
"object",
"null"
],
"description": "The storage destination that keeps the copy, null when it was deleted.",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"snapshot_id": {
"type": "string",
"description": "The restic snapshot ID in that repository."
},
"availability": {
"$ref": "#\/components\/schemas\/SnapshotAvailability"
}
},
"required": [
"repository_id",
"storage_destination",
"snapshot_id",
"availability"
]
}
},
"taken_at": {
"type": [
"string",
"null"
],
"description": "When the backup that made the snapshot finished."
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"snapshot_id",
"job",
"run_id",
"availability",
"source_bytes",
"stored_bytes",
"database",
"kept_forever_at",
"copies",
"taken_at",
"created_at"
],
"title": "Snapshot"
},
"SnapshotAvailability": {
"type": "string",
"x-extensible-enum": [
"available",
"expired",
"unknown"
],
"title": "SnapshotAvailability"
},
"SourceInspection": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted source inspection ID, pass it as source_inspection when saving the backup job.",
"examples": [
"inspection_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"server": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted server ID.",
"examples": [
"server_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"status": {
"description": "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.",
"$ref": "#\/components\/schemas\/AgentCommandStatus"
},
"successful": {
"type": "boolean",
"description": "Whether the source can be used: the test completed successfully. The job must be saved within 10 minutes of completion."
},
"result": {
"type": [
"object",
"null"
],
"description": "What the agent found, null until the test completed.",
"properties": {
"code": {
"description": "success, or why the test failed.",
"$ref": "#\/components\/schemas\/SourceInspectionResultCode"
},
"summary": {
"type": "string",
"description": "What the agent reported.",
"examples": [
"Synthetic directory access verified."
]
},
"databases": {
"type": "array",
"description": "Databases the user can access, for database sources.",
"items": {
"type": "string"
}
}
},
"required": [
"code",
"summary",
"databases"
]
},
"guidance": {
"type": [
"object",
"null"
],
"description": "How to fix a failed test, null unless the test failed.",
"properties": {
"stage": {
"description": "The step of the test that failed.",
"$ref": "#\/components\/schemas\/SourceInspectionFailureStage"
},
"action": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"stage",
"action",
"detail"
]
},
"expires_at": {
"type": "string",
"description": "When the agent must have picked the test up."
},
"completed_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"server",
"status",
"successful",
"result",
"guidance",
"expires_at",
"completed_at",
"created_at"
],
"title": "SourceInspection"
},
"SourceInspectionFailureStage": {
"type": "string",
"x-extensible-enum": [
"source_validation",
"source_access",
"tool_check",
"credential_setup",
"database_discovery",
"database_selection",
"table_selection",
"dump_test",
"dump_execution",
"unknown"
],
"title": "SourceInspectionFailureStage"
},
"SourceInspectionResultCode": {
"type": "string",
"description": "The result of a source inspection: success, or why the agent could not use the source.\n",
"x-extensible-enum": [
"success",
"invalid_root",
"tool_unavailable",
"source_authentication_failed",
"database_selection_invalid",
"table_selection_invalid",
"execution_failed"
],
"title": "SourceInspectionResultCode"
},
"StorageDestination": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Formatted storage destination ID.",
"examples": [
"storage_01j8q8zk2f4m6n7p9r1s3t5v7x"
]
},
"name": {
"type": "string",
"examples": [
"Production S3"
]
},
"driver": {
"description": "Where repositories are stored: s3 for S3-compatible storage, sftp for an SFTP server, local for development storage.\n| |\n|---|\n| `s3` The S3 storage driver, which can be used with any S3-compatible storage services. |\n| `sftp` SFTP storage authenticated by password or a generated Ed25519 key. |\n| `local` Development only storage driver, should never be used in production. |",
"$ref": "#\/components\/schemas\/StorageDriver"
},
"location": {
"type": "string",
"description": "Human-readable location of the destination.",
"examples": [
"https:\/\/s3.example.com\/backups\/backupchief"
]
},
"settings": {
"description": "The settings of the driver: S3StorageSettings for s3, SftpStorageSettings for sftp, LocalStorageSettings for local. Credentials are never returned.",
"anyOf": [
{
"$ref": "#\/components\/schemas\/S3StorageSettings"
},
{
"$ref": "#\/components\/schemas\/SftpStorageSettings"
},
{
"$ref": "#\/components\/schemas\/LocalStorageSettings"
}
]
},
"credentials_updated_at": {
"type": [
"string",
"null"
],
"description": "When the credentials were last replaced, null when they never changed."
},
"servers_on_previous_credentials": {
"type": "integer",
"description": "Servers that did not apply the latest credentials yet. Wait until this is 0 before revoking the old credentials at the provider."
},
"in_use": {
"type": "boolean",
"description": "Whether a backup job keeps its main copy or an extra copy here, which prevents deleting the destination and changing its location."
},
"jobs_count": {
"type": "integer",
"description": "Backup jobs that keep their main copy here."
},
"extra_copies_count": {
"type": "integer",
"description": "Backup jobs that keep an extra copy here."
},
"stored_bytes": {
"type": [
"integer",
"null"
],
"description": "Bytes the repositories at this destination last reported, null until any was measured."
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"driver",
"location",
"settings",
"credentials_updated_at",
"servers_on_previous_credentials",
"in_use",
"jobs_count",
"extra_copies_count",
"stored_bytes",
"created_at"
],
"title": "StorageDestination"
},
"StorageDriver": {
"type": "string",
"description": "| |\n|---|\n| `s3` The S3 storage driver, which can be used with any S3-compatible storage services. |\n| `sftp` SFTP storage authenticated by password or a generated Ed25519 key. |\n| `local` Development only storage driver, should never be used in production. |",
"x-extensible-enum": [
"s3",
"sftp",
"local"
],
"title": "StorageDriver"
},
"Team": {
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Team slug, the value of the X-Chief-Team header.",
"examples": [
"acme"
]
},
"name": {
"type": "string",
"examples": [
"Acme"
]
},
"timezone": {
"type": [
"string",
"null"
],
"description": "Timezone of the team.",
"examples": [
"Europe\/Amsterdam"
]
},
"agent_auto_updates": {
"type": "boolean",
"description": "Whether servers install new agent releases automatically, unless a server overrides it."
},
"limits": {
"type": "object",
"description": "The plan limits of the team. A null limit is unlimited.",
"properties": {
"jobs": {
"type": "object",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"description": "Backup jobs the team may have, null for unlimited."
},
"usage": {
"type": "integer"
}
},
"required": [
"limit",
"usage"
]
},
"servers": {
"type": "object",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"description": "Enrolled servers the team may have, null for unlimited."
},
"usage": {
"type": "integer"
}
},
"required": [
"limit",
"usage"
]
},
"storage_destinations": {
"type": "object",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"description": "Storage destinations the team may have, null for unlimited."
},
"usage": {
"type": "integer"
}
},
"required": [
"limit",
"usage"
]
},
"minimum_schedule_interval_seconds": {
"type": [
"integer",
"null"
],
"description": "Shortest interval between scheduled backups in seconds, null without a minimum."
},
"downloads": {
"type": "object",
"properties": {
"max_bytes": {
"type": [
"integer",
"null"
],
"description": "Largest size of a hosted download in bytes, null for unlimited."
},
"active_limit": {
"type": [
"integer",
"null"
],
"description": "Hosted downloads that can be prepared or ready at once, null for unlimited."
},
"staged_bytes_limit": {
"type": [
"integer",
"null"
],
"description": "Bytes all ready hosted downloads may take together, null for unlimited."
},
"per_day": {
"type": [
"integer",
"null"
],
"description": "Hosted downloads that can be requested per day, null for unlimited."
}
},
"required": [
"max_bytes",
"active_limit",
"staged_bytes_limit",
"per_day"
]
}
},
"required": [
"jobs",
"servers",
"storage_destinations",
"minimum_schedule_interval_seconds",
"downloads"
]
}
},
"required": [
"slug",
"name",
"timezone",
"agent_auto_updates",
"limits"
],
"title": "Team"
}
},
"responses": {
"AuthenticationException": {
"description": "Unauthenticated",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
},
"ValidationException": {
"description": "Validation error",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Errors overview."
},
"errors": {
"type": "object",
"description": "A detailed description of each field that failed validation.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"message",
"errors"
]
}
}
}
},
"ModelNotFoundException": {
"description": "Not found",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}
}
}
}
}
}
}