Export and restore

Adopt a backup folder

Starts afresh on a disk that replaced the backup folder's disk, when the folder holds no store marker for this instance. Marfa forgets the backups and file copies of the old disk and changes no other store. Requires backups.manage.

POST
/backups/folder/adopt

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Response body

About errors

Returns the new store and what Marfa forgot of the old one.

application/json
  1. response
store_id*string

The ID of the store the backup folder's files folder is now.

replaced_store_id*string

The ID of the store Marfa forgot. GET /blobs/stores lists it as detached.

backups_forgotten*integer

How many backups in the old store Marfa forgot.

Range0 <= value
copies_forgotten*integer

How many copies of files in the old store Marfa forgot.

Range0 <= value
  • validation_error: the query has a parameter this endpoint doesn't take.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: the credential lacks backups.manage. details.required_scope names it.
application/json
  1. response

An error response.

error*

What went wrong.

  • conflict: the backup folder holds this instance's files, so there is nothing to adopt, its files folder holds another store's marker, or the instance backs up to an object store.
  • housekeeping_job_running: a backup is running. Try again once it ends.
  • no_backup_destination: the instance has nowhere to put backups, so it keeps none.
application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

blob_store_unavailable: the backup folder is not there, or Marfa could not write the new store marker after it forgot the old disk's backups and file copies. Mount the disk it is on, or make the folder writable, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X POST 'http://localhost:8600/backups/folder/adopt'
About errors
{  "store_id": "01926a3c-8d2e-7a41-b5c6-2f9e0d4a7b13",  "replaced_store_id": "01926a3c-4b1d-7e52-9a8f-3c5d7e1b2a40",  "backups_forgotten": 3,  "copies_forgotten": 41}