Add a backup destination

POST

/backup-destinations

curl --request POST \
  --url https://example.com/api/v1/backup-destinations \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "name": "example", "kind": "NODE_DIRECTORY", "subdirectory": "example", "s3": { "endpoint": "example", "bucket": "example", "region": "example", "prefix": "example", "accessKeyId": "example", "secretAccessKey": "example", "caPem": "example" } }'

Global administrators only; audited. Shardkeep generates the destination’s age key pair: backups are encrypted to it before they leave a Node. The private key comes back once, as recoveryKey: keep it offline, as it decrypts every backup stored there even without Shardkeep.

Authorizations

• sessionCookie
• bearerToken

Request Body^required

Media typeapplication/json

object

name

required

string

>= 1 characters <= 100 characters

kind

required

string

Allowed values: NODE_DIRECTORY S3

subdirectory

string

<= 64 characters

s3

object

endpoint

required

Host name and optional port; HTTPS is always used.

string

<= 255 characters

bucket

required

string

<= 63 characters

region

string

<= 64 characters

prefix

string

<= 255 characters

accessKeyId

required

string

<= 255 characters

secretAccessKey

Required when adding; omit to keep the stored one.

string

<= 255 characters

caPem

PEM certificates to trust in addition to the system roots, for a self-signed endpoint.

string

<= 65536 characters

Responses

201

Destination added.

Media typeapplication/json

object

destination

required

object

id

required

string format: uuid

name

required

string

kind

required

string

Allowed values: NODE_DIRECTORY S3

subdirectory

For NODE_DIRECTORY, the directory below each Agent’s -backup-dir.

string

s3

object

endpoint

required

string

bucket

required

string

region

required

string

prefix

required

string

accessKeyId

required

string

customCa

required

Whether extra CA certificates are trusted for the endpoint.

boolean

recipient

required

The age public key backups are encrypted to.

string

createdAt

required

string format: date-time

recoveryKey

required

The age private key (AGE-SECRET-KEY-1…) that decrypts this destination’s backups. Shown only once.

string

Example

{
  "destination": {
    "kind": "NODE_DIRECTORY"
  }
}

400

The request is invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

401

Not signed in, or the credentials are invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

403

Signed in, but not allowed.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

409

Clashes with existing data or state.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}