Storage destinations

Download schema

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.

List storage destinations

GET

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

/storage-destinations

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the team's storage destinations by name.

List storage destinations › query Parameters

query

string | null · maxLength: 255

Search results by name.

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 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.

Enum values:

attention

in_use

unused

List storage destinations › Responses

Paginated set of StorageDestination

StorageDestination[] · required

object · required

GET/storage-destinations

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

Example Responses

{
  "data": [
    {
      "id": "storage_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "Production S3",
      "driver": "s3",
      "location": "https://s3.example.com/backups/backupchief",
      "settings": {
        "endpoint": "https://s3.eu-central-1.amazonaws.com",
        "region": "eu-central-1",
        "bucket": "backups",
        "root_path": "backupchief"
      },
      "credentials_updated_at": "credentials_updated_at",
      "servers_on_previous_credentials": 0,
      "in_use": true,
      "jobs_count": 0,
      "extra_copies_count": 0,
      "stored_bytes": 0,
      "created_at": "created_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

Create a storage destination

POST

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

/storage-destinations

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Create a storage destination › Request Body

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

SaveStorageDestinationRequest

name

string · maxLength: 255 · required

Display name of the destination, unique within the team.

Example: Production S3

driver

string · enum · required

Storage driver. local is only available in development.

Enum values:

sftp

Example: s3

object · required

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

Create a storage destination › Responses

The storage destination was created.

StorageDestination · required

POST/storage-destinations

curl https://backup.chief.app/api/v1/storage-destinations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Production S3",
  "driver": "s3",
  "settings": {
    "endpoint": "https://s3.eu-central-1.amazonaws.com",
    "region": "eu-central-1",
    "bucket": "backups",
    "root_path": "backupchief",
    "access_key_id": "access_key_id",
    "secret_access_key": "secret_access_key",
    "host": "storage.example.com",
    "port": 22,
    "username": "backup",
    "password": "password",
    "reset_host_keys": true,
    "path": "backups/local"
  }
}'

Example Request Body

{
  "name": "Production S3",
  "driver": "s3",
  "settings": {
    "endpoint": "https://s3.eu-central-1.amazonaws.com",
    "region": "eu-central-1",
    "bucket": "backups",
    "root_path": "backupchief",
    "access_key_id": "access_key_id",
    "secret_access_key": "secret_access_key",
    "host": "storage.example.com",
    "port": 22,
    "username": "backup",
    "password": "password",
    "reset_host_keys": true,
    "path": "backups/local"
  }
}

json

Example Responses

{
  "data": {
    "id": "storage_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Production S3",
    "driver": "s3",
    "location": "https://s3.example.com/backups/backupchief",
    "settings": {
      "endpoint": "https://s3.eu-central-1.amazonaws.com",
      "region": "eu-central-1",
      "bucket": "backups",
      "root_path": "backupchief"
    },
    "credentials_updated_at": "credentials_updated_at",
    "servers_on_previous_credentials": 0,
    "in_use": true,
    "jobs_count": 0,
    "extra_copies_count": 0,
    "stored_bytes": 0,
    "created_at": "created_at"
  }
}

json

application/json

Get a storage destination

GET

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

/storage-destinations/{destination}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get one of the team's storage destinations with its settings and the jobs that use it. Credentials are never returned.

Get a storage destination › path Parameters

destination

string · required

Get a storage destination › Responses

StorageDestination

StorageDestination · required

Update a storage destination

PATCH

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

/storage-destinations/{destination}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

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.

Once 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.

Update a storage destination › path Parameters

destination

string · required

Update a storage destination › Request Body

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

SaveStorageDestinationRequest

name

string · maxLength: 255 · required

Display name of the destination, unique within the team.

Example: Production S3

driver

string · enum · required

Storage driver. local is only available in development.

Enum values:

sftp

Example: s3

object · required

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

Update a storage destination › Responses

StorageDestination

StorageDestination · required

PATCH/storage-destinations/{destination}

curl https://backup.chief.app/api/v1/storage-destinations/:destination \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Production S3",
  "driver": "s3",
  "settings": {
    "endpoint": "https://s3.eu-central-1.amazonaws.com",
    "region": "eu-central-1",
    "bucket": "backups",
    "root_path": "backupchief",
    "access_key_id": "access_key_id",
    "secret_access_key": "secret_access_key",
    "host": "storage.example.com",
    "port": 22,
    "username": "backup",
    "password": "password",
    "reset_host_keys": true,
    "path": "backups/local"
  }
}'

Example Request Body

{
  "name": "Production S3",
  "driver": "s3",
  "settings": {
    "endpoint": "https://s3.eu-central-1.amazonaws.com",
    "region": "eu-central-1",
    "bucket": "backups",
    "root_path": "backupchief",
    "access_key_id": "access_key_id",
    "secret_access_key": "secret_access_key",
    "host": "storage.example.com",
    "port": 22,
    "username": "backup",
    "password": "password",
    "reset_host_keys": true,
    "path": "backups/local"
  }
}

json

Example Responses

{
  "data": {
    "id": "storage_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Production S3",
    "driver": "s3",
    "location": "https://s3.example.com/backups/backupchief",
    "settings": {
      "endpoint": "https://s3.eu-central-1.amazonaws.com",
      "region": "eu-central-1",
      "bucket": "backups",
      "root_path": "backupchief"
    },
    "credentials_updated_at": "credentials_updated_at",
    "servers_on_previous_credentials": 0,
    "in_use": true,
    "jobs_count": 0,
    "extra_copies_count": 0,
    "stored_bytes": 0,
    "created_at": "created_at"
  }
}

json

application/json

Delete a storage destination

DELETE

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

/storage-destinations/{destination}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete a destination that no backup job keeps a main or extra copy at. The data at the destination itself is not touched.

Delete a storage destination › path Parameters

destination

string · required

Delete a storage destination › Responses

The storage destination was deleted.

string

Servers Backup jobs