Buckets and backups

Use an existing bucket

POST/buckets/existing

"Use an existing bucket": the Environment's bucket entry stands for an S3 bucket the operator already has, looked up at every plan and never changed.

Who can call it: Owner or Admin. Needs service: create, which a custom role can also grant.

Request body

Responses

201 Created

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/buckets/existing \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "environmentId": "UVFRqyCfWEtSm6NdDvrZc",
    "configName": "example",
    "bucketName": "example"
  }'

Read reach for an existing bucket

GET/buckets/existing/reach

What the "Use an existing bucket" form shows: on Google Cloud the roles/storage.legacyBucketReader grant a bucket in another project needs so every plan can look it up; on AWS.

Who can call it: Owner or Admin. Needs service: create, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/buckets/existing/reach?environmentId=UVFRqyCfWEtSm6NdDvrZc" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get a bucket

GET/buckets/{id}

The bucket's page; an existing bucket on Google Cloud's access is checked again.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Delete a bucket

DELETE/buckets/{id}

Keeps a bucket that holds files and names it as left behind (bucketLeftBehind), and removes an empty one whole.

Who can call it: Owner or Admin. Needs service: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE "https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC?deleteFiles=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set upload origins

PUT/buckets/{id}/origins

The bucket's whole browser-upload origin list, an ordinary Service update.

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Request body

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC/origins \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "origins": [
      "example"
    ]
  }'

Rotate a bucket's key

POST/buckets/{id}/rotate-key

Rotate key: a new key, a redeploy of every Service linking the bucket's key, and only then the old key's removal. An ordinary Service update. Answers once the redeploys are queued, with the bucket whose keyRotation then follows them to their end.

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC/rotate-key \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Retry deleting a bucket

POST/buckets/{id}/delete/retry

Retry a bucket on AWS's incomplete Delete: another destroy-only Cloud run from the kept state, emptying it again first if its Delete asked.

Who can call it: Owner or Admin. Needs service: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC/delete/retry \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Forget the incomplete delete of a bucket

POST/buckets/{id}/delete/forget

Forget a bucket on AWS's incomplete Delete: the row dropped, what is left in AWS written into the audit entry.

Who can call it: Owner or Admin. Needs service: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/buckets/RAU6yAYUXFRdXdPLyLoPC/delete/forget \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List backups for a Service

GET/backups

Who can call it: Owner, Admin or Member. Needs backup: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/backups?serviceId=ikGaJLrdLoCZDcimNaVV3&serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a backup

POST/backups

Who can call it: Owner, Admin or Member. Needs backup: create, which a custom role can also grant.

Request body

Responses

201 Created

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/backups \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "prefix": "ci",
    "database": "example",
    "destinationId": "ULX2acJSVhXEsZABPDxLh",
    "databaseType": "postgres",
    "serviceId": "ikGaJLrdLoCZDcimNaVV3"
  }'

Restore a backup

POST/backups/restore

Who can call it: Owner, Admin or Member. Needs backup: restore, which a custom role can also grant.

Request body

Responses

204 No content

Done. The answer has no body.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/backups/restore \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "databaseId": "2wSsHYv3jCBNZyD8omEe2",
    "databaseType": "postgres",
    "databaseName": "example",
    "backupFile": "example",
    "destinationId": "ULX2acJSVhXEsZABPDxLh"
  }'

List backup files

GET/backups/files

Who can call it: Owner, Admin or Member. Needs backup: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/backups/files?destinationId=ULX2acJSVhXEsZABPDxLh" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get a backup

GET/backups/{id}

Who can call it: Owner, Admin or Member. Needs backup: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a backup

PATCH/backups/{id}

Who can call it: Owner, Admin or Member. Needs backup: update, which a custom role can also grant.

Parameters

Request body

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "enabled": true,
    "prefix": "ci"
  }'

Delete a backup

DELETE/backups/{id}

Who can call it: Owner, Admin or Member. Needs backup: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Run a backup now

POST/backups/{id}/run

Who can call it: Owner, Admin or Member. Needs backup: create, which a custom role can also grant.

Parameters

Responses

204 No content

Done. The answer has no body.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/backups/RAU6yAYUXFRdXdPLyLoPC/run \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List volume backups for a Service

GET/volume-backups

Who can call it: Owner, Admin or Member. Needs volumeBackup: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/volume-backups?serviceId=ikGaJLrdLoCZDcimNaVV3&serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a volume backup

POST/volume-backups

Who can call it: Owner, Admin or Member. Needs volumeBackup: create, which a custom role can also grant.

Request body

Responses

201 Created

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/volume-backups \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "volumeName": "example",
    "prefix": "ci",
    "schedule": "0 3 * * *",
    "serviceId": "ikGaJLrdLoCZDcimNaVV3",
    "destinationId": "ULX2acJSVhXEsZABPDxLh"
  }'

Restore a volume backup

POST/volume-backups/restore

204, and both of this controller's 204s are void by design. restore answers nothing because its whole diagnosis is the rclone script's stdout, which reaches the caller as a 400/409 message — success has nothing left to say.

Who can call it: Owner, Admin or Member. Needs volumeBackup: restore, which a custom role can also grant.

Request body

Responses

204 No content

Done. The answer has no body.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/volume-backups/restore \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serviceId": "ikGaJLrdLoCZDcimNaVV3",
    "serviceType": "application",
    "volumeName": "example",
    "backupFileName": "example",
    "destinationId": "ULX2acJSVhXEsZABPDxLh"
  }'

Get a volume backup

GET/volume-backups/{id}

Who can call it: Owner, Admin or Member. Needs volumeBackup: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/volume-backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a volume backup

PATCH/volume-backups/{id}

Who can call it: Owner, Admin or Member. Needs volumeBackup: update, which a custom role can also grant.

Parameters

Request body

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/volume-backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "volumeName": "example",
    "prefix": "ci"
  }'

Delete a volume backup

DELETE/volume-backups/{id}

Who can call it: Owner, Admin or Member. Needs volumeBackup: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/volume-backups/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Run a volume backup now

POST/volume-backups/{id}/run

Who can call it: Owner, Admin or Member. Needs volumeBackup: create, which a custom role can also grant.

Parameters

Responses

204 No content

Done. The answer has no body.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/volume-backups/RAU6yAYUXFRdXdPLyLoPC/run \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List backup destinations

GET/destinations

Who can call it: Owner or Admin. Needs destination: read, which a custom role can also grant.

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/destinations \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a backup destination

POST/destinations

Who can call it: Owner or Admin. Needs destination: create, which a custom role can also grant.

Request body

Responses

201 Created

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/destinations \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "offsite-backups",
    "accessKey": "<secret>",
    "secretAccessKey": "<secret>",
    "bucket": "example",
    "region": "eu-central-1",
    "endpoint": "https://northwind.dev"
  }'

Test a connection to a backup destination

POST/destinations/test-connection

Who can call it: Owner or Admin. Needs destination: create, which a custom role can also grant.

Request body

Responses

204 No content

Done. The answer has no body.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/destinations/test-connection \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "offsite-backups",
    "accessKey": "<secret>",
    "secretAccessKey": "<secret>",
    "bucket": "example",
    "region": "eu-central-1",
    "endpoint": "https://northwind.dev"
  }'

Test a saved backup destination

POST/destinations/{id}/test-connection

The same probe against a destination that is already saved. The credentials come off the row server-side, because the read path strips the secret and so the console has nothing to send.

Who can call it: Owner or Admin. Needs destination: create, which a custom role can also grant.

Parameters

Request body

Responses

204 No content

Done. The answer has no body.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/destinations/RAU6yAYUXFRdXdPLyLoPC/test-connection \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverId": "Ni7mAbWKjbWy4KErPjtrY"
  }'

Get a backup destination

GET/destinations/{id}

Who can call it: Owner or Admin. Needs destination: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/destinations/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a backup destination

PATCH/destinations/{id}

Who can call it: Owner or Admin. Needs destination: create, which a custom role can also grant.

Parameters

Request body

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/destinations/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "offsite-backups",
    "provider": "example",
    "accessKey": "<secret>"
  }'

Delete a backup destination

DELETE/destinations/{id}

Who can call it: Owner or Admin. Needs destination: delete, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/destinations/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List objects

GET/destinations/{id}/objects

What is actually in the bucket, so a restore can pick it.

Who can call it: Owner or Admin. Needs destination: read, which a custom role can also grant.

Parameters

Responses

200 OK

The result, as JSON.

Refusals

400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/destinations/RAU6yAYUXFRdXdPLyLoPC/objects \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"