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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
Returns the backup Marfa put, the bytes it sent, how many old backups it deleted, and the files it lost.
application/json- response
outcome*"put"Always put.
"put"backup*A backup in the instance's backup folder or object store.
sent_bytes*integerHow 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.
0 <= valueremoved*integerHow many old backups Marfa deleted.
0 <= valueunremoved*integerHow many old backups Marfa tried to delete and couldn't. It tries again after the next backup.
0 <= valueblobs_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*integerHow 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.
0 <= valuevalidation_error: the query has a parameter this endpoint doesn't take.
application/json- 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- response
An error response.
error*What went wrong.
forbidden: the credential lacksbackups.manage.details.required_scopenames it.
application/json- 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 thatGET /exportrefuses, named indetails.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- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X POST 'http://localhost:8600/backups'{ "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}