Export and restore

Take a backup

Takes a backup now and puts it in the instance's backup folder or object store, whether or not anything changed since the last one, then deletes this instance's backups that thinning no longer keeps. Requires backups.manage.

POST
/backups

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Response body

About errors

Returns the backup Marfa put, the bytes it sent, how many old backups it deleted, and the files it lost.

application/json
  1. response
outcome*"put"

Always put.

Value in"put"
backup*

A backup in the instance's backup folder or object store.

sent_bytes*integer

How many bytes of parts Marfa stored for the backup that the destination didn't already hold. A backup of an instance that hasn't changed since the last one stores only its manifest, and this is 0.

Range0 <= value
removed*integer

How many old backups Marfa deleted.

Range0 <= value
unremoved*integer

How many old backups Marfa tried to delete and couldn't. It tries again after the next backup.

Range0 <= value
blobs_lost*array<string>

The hashes of the files the backup names that no store could give when Marfa took it. A restore of the backup goes ahead without them, and GET /health answers backups.status failing until a backup is put without losing any.

blobs_waiting*integer

How many files the backup names with no recorded copy in the destination, blobs_lost included. blob-integrity keeps the record true. A restore needs those files unless the restoring instance holds them or the backup lists them as lost.

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: a file the backup names was purged or dropped while it was read, or the name is taken.
  • export_entry_unrestorable: the backup would hold an item or edge that GET /export refuses, named in details.entry, so none was put.
  • housekeeping_job_running: a backup is running. Try again once it ends.
  • no_backup_destination: the instance has nowhere to put backups.
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, the object store or the blob folder failed, or didn't answer in time. Try again later.

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'
About errors
{  "outcome": "put",  "backup": {    "name": "20261003T102400.836Z.json",    "instance_id": "01a10128-f3e1-7ab1-b58c-a89836a748a8",    "created_at": "2026-10-03T10:24:00.836Z",    "size_bytes": 8192  },  "sent_bytes": 4096,  "removed": 0,  "unremoved": 0,  "blobs_lost": [],  "blobs_waiting": 0}