Downloads

Download schema

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.

List downloads

GET

https://backup.chief.app/api/v1

/downloads

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the hosted downloads of all the team's backup jobs, newest first.

List downloads › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

status

string | null · enum

Only return downloads that are available (ready and not expired), in_progress (being prepared or deleted) or history (failed, cancelled or expired).

Enum values:

available

in_progress

history

job

string | null

Only return the downloads of this backup job.

List downloads › Responses

Paginated set of Download

Download[] · required

object · required

GET/downloads

curl https://backup.chief.app/api/v1/downloads \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "job": {
        "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "repository": {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        }
      },
      "kind": "file",
      "name": "invoices-4f2a9c1d.zip",
      "status": "queued",
      "status_label": "Preparing ZIP",
      "downloadable": true,
      "source_bytes": 0,
      "archive_bytes": 0,
      "uploaded_bytes": 0,
      "sha256": "sha256",
      "failure_code": "source_too_large",
      "failure_message": "failure_message",
      "download_count": 0,
      "requested_by": "requested_by",
      "created_at": "created_at",
      "started_at": "started_at",
      "ready_at": "ready_at",
      "expires_at": "expires_at",
      "last_downloaded_at": "last_downloaded_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List the downloads of a backup job

GET

https://backup.chief.app/api/v1

/jobs/{job}/downloads

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the hosted downloads of one backup job, newest first.

List the downloads of a backup job › path Parameters

job

string · required

List the downloads of a backup job › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

status

string | null · enum

Only return downloads that are available (ready and not expired), in_progress (being prepared or deleted) or history (failed, cancelled or expired).

Enum values:

available

in_progress

history

job

string | null

Only return the downloads of this backup job.

List the downloads of a backup job › Responses

Paginated set of Download

Download[] · required

object · required

GET/jobs/{job}/downloads

curl https://backup.chief.app/api/v1/jobs/:job/downloads \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "job": {
        "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "repository": {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        }
      },
      "kind": "file",
      "name": "invoices-4f2a9c1d.zip",
      "status": "queued",
      "status_label": "Preparing ZIP",
      "downloadable": true,
      "source_bytes": 0,
      "archive_bytes": 0,
      "uploaded_bytes": 0,
      "sha256": "sha256",
      "failure_code": "source_too_large",
      "failure_message": "failure_message",
      "download_count": 0,
      "requested_by": "requested_by",
      "created_at": "created_at",
      "started_at": "started_at",
      "ready_at": "ready_at",
      "expires_at": "expires_at",
      "last_downloaded_at": "last_downloaded_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Prepare a download

POST

https://backup.chief.app/api/v1

/jobs/{job}/downloads

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Prepare a download › path Parameters

job

string · required

Prepare a download › Request Body

CreateDownloadRequest

snapshot

string · required

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

Example: snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x

path

string | null · maxLength: 4096

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

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

path_type

string | null · enum

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

Enum values:

file

Prepare a download › Responses

The download is being prepared, or an earlier download of the same content is returned.

Download · required

POST/jobs/{job}/downloads

curl https://backup.chief.app/api/v1/jobs/:job/downloads \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "snapshot": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
  "path": "/var/www/shop/storage/invoices",
  "path_type": "file",
  "repository": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
}'

Example Request Body

{
  "snapshot": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
  "path": "/var/www/shop/storage/invoices",
  "path_type": "file",
  "repository": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x"
}

json

Example Responses

{
  "data": {
    "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "repository": {
      "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "storage_destination": {
        "id": "id",
        "name": "name"
      }
    },
    "kind": "file",
    "name": "invoices-4f2a9c1d.zip",
    "status": "queued",
    "status_label": "Preparing ZIP",
    "downloadable": true,
    "source_bytes": 0,
    "archive_bytes": 0,
    "uploaded_bytes": 0,
    "sha256": "sha256",
    "failure_code": "source_too_large",
    "failure_message": "failure_message",
    "download_count": 0,
    "requested_by": "requested_by",
    "created_at": "created_at",
    "started_at": "started_at",
    "ready_at": "ready_at",
    "expires_at": "expires_at",
    "last_downloaded_at": "last_downloaded_at"
  }
}

json

application/json

Get a download

GET

https://backup.chief.app/api/v1

/downloads/{download}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get one hosted download, to follow its preparation until it is ready.

Get a download › path Parameters

download

string · required

Get a download › Responses

Download

Download · required

GET/downloads/{download}

curl https://backup.chief.app/api/v1/downloads/:download \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "repository": {
      "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "storage_destination": {
        "id": "id",
        "name": "name"
      }
    },
    "kind": "file",
    "name": "invoices-4f2a9c1d.zip",
    "status": "queued",
    "status_label": "Preparing ZIP",
    "downloadable": true,
    "source_bytes": 0,
    "archive_bytes": 0,
    "uploaded_bytes": 0,
    "sha256": "sha256",
    "failure_code": "source_too_large",
    "failure_message": "failure_message",
    "download_count": 0,
    "requested_by": "requested_by",
    "created_at": "created_at",
    "started_at": "started_at",
    "ready_at": "ready_at",
    "expires_at": "expires_at",
    "last_downloaded_at": "last_downloaded_at"
  }
}

json

application/json

Delete a ready download

DELETE

https://backup.chief.app/api/v1

/downloads/{download}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete the ZIP of a ready download before it expires. Download URLs created for it stop working. The download stays listed in the history.

Delete a ready download › path Parameters

download

string · required

Delete a ready download › Responses

Download

Download · required

DELETE/downloads/{download}

curl https://backup.chief.app/api/v1/downloads/:download \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "repository": {
      "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "storage_destination": {
        "id": "id",
        "name": "name"
      }
    },
    "kind": "file",
    "name": "invoices-4f2a9c1d.zip",
    "status": "queued",
    "status_label": "Preparing ZIP",
    "downloadable": true,
    "source_bytes": 0,
    "archive_bytes": 0,
    "uploaded_bytes": 0,
    "sha256": "sha256",
    "failure_code": "source_too_large",
    "failure_message": "failure_message",
    "download_count": 0,
    "requested_by": "requested_by",
    "created_at": "created_at",
    "started_at": "started_at",
    "ready_at": "ready_at",
    "expires_at": "expires_at",
    "last_downloaded_at": "last_downloaded_at"
  }
}

json

application/json

Cancel a download

POST

https://backup.chief.app/api/v1

/downloads/{download}/cancel

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Cancel a download › path Parameters

download

string · required

Cancel a download › Responses

Download

Download · required

POST/downloads/{download}/cancel

curl https://backup.chief.app/api/v1/downloads/:download/cancel \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "download_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "snapshot_id": "snapshot_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "run_id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "repository": {
      "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "storage_destination": {
        "id": "id",
        "name": "name"
      }
    },
    "kind": "file",
    "name": "invoices-4f2a9c1d.zip",
    "status": "queued",
    "status_label": "Preparing ZIP",
    "downloadable": true,
    "source_bytes": 0,
    "archive_bytes": 0,
    "uploaded_bytes": 0,
    "sha256": "sha256",
    "failure_code": "source_too_large",
    "failure_message": "failure_message",
    "download_count": 0,
    "requested_by": "requested_by",
    "created_at": "created_at",
    "started_at": "started_at",
    "ready_at": "ready_at",
    "expires_at": "expires_at",
    "last_downloaded_at": "last_downloaded_at"
  }
}

json

application/json

Create a download URL

POST

https://backup.chief.app/api/v1

/downloads/{download}/url

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Create a download URL › path Parameters

download

string · required

Create a download URL › Responses

object · required

Snapshots