Export and restore

List backups

Returns the backups in the instance's backup folder or object store, newest first, including those another instance took there, so a new instance can restore the one it replaces. Requires backups.manage.

GET
/backups

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Response body

About errors

Returns every backup, in one page. A backup is a manifest and the parts it names, which together make an archive of every item, edge and instance line, the trash included, without file bytes, which the backup folder or object store already holds. A part an earlier backup stored unchanged is stored once.

application/json
  1. response
data*array<>

The backups, newest first.

next_cursor*null

Always null: every backup is in one page.

  • 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.

no_backup_destination: the instance has nowhere to put backups, so it keeps none. Set backup_path to a folder, or object_store_bucket to an object store, to keep them.

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 or object store 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 GET 'http://localhost:8600/backups'
About errors
{  "data": [    {      "name": "20261003T102400.836Z.json",      "instance_id": "01a10128-f3e1-7ab1-b58c-a89836a748a8",      "created_at": "2026-10-03T10:24:00.836Z",      "size_bytes": 8192    }  ],  "next_cursor": null}