Export and restore

Export an archive

Exports an archive of the items, metadata and edges you can read, excluding trash unless requested. An archive can be read by POST /restore.

GET
/export

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Query parameters

type?string

Only export items of these types and their subtypes: a comma-separated list of up to 10, such as core.note,app.*. A wildcard such as core.* matches every type under that prefix.

state?string

Only export items in these lifecycle states: one state or a comma-separated list, such as active,archived. Without it, you get every state but trashed. Send any on its own to include trashed items too.

source?string

Only export items stamped with this source.

occurred_after?string

Only export items whose own time (occurred_at, else created_at) is after this time.

occurred_before?string

Only export items whose own time (occurred_at, else created_at) is before this time.

format?string

ndjson for lines of JSON, or archive for a tar file that POST /restore reads. Defaults to ndjson. An archive's files.ndjson.gz marks each file it doesn't carry not_carried, including one your credential can't read.

Value in"ndjson""archive"
files?boolean

With format=archive, false leaves out the bytes of files, which files.ndjson.gz then marks not_carried. format=ndjson carries no file bytes either way.

Defaulttrue

Response body

About errors

With format=ndjson, one JSON object per line: each item, then each readable edge between them. With format=archive, a tar of the manifest, compressed lines of its files, registrations and settings, items, versions, edges and table rows, then the blobs. If the export fails partway or your credential ends or stops reading what it carries, the connection ends early and an archive won't unpack.

response?string
  • validation_error: a query parameter is unknown or invalid, such as a format other than ndjson or archive, a state that isn't a lifecycle state or any, or a time that isn't a timestamp.
  • unknown_type: type is a concrete type that nothing registers.
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.

  • type_not_permitted: your credential reaches no type, or type names a type you can't read with none readable under it.
application/json
  1. response

An error response.

error*

What went wrong.

  • enforcement_unreadable: with format=archive, the instance's enforcement settings do not read. Set them again with PATCH /config, then export again.
  • export_entry_unrestorable: with format=archive, a restore would refuse or skip an item or edge, or its line is over the 64 MiB a restore reads. details.entry names it and why. Correct it or its type, then export again.
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: a blob store failed, or didn't answer in time, while Marfa checked a blob's copy, or Marfa couldn't write the archive's working files in the blob folder. Try again later.
  • write_contention: the database was busy. Nothing changed. Try the request 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 GET 'http://localhost:8600/export'
About errors
"{\"item\":{\"id\":\"01a1011a-4902-76cf-a4a9-88e99c038c8d\",\"type\":\"acme.deal\",\"state\":\"active\",\"tier\":\"library\",\"created_at\":\"2026-10-03T09:37:25.975Z\",\"updated_at\":\"2026-10-03T09:53:05.280Z\",\"last_activity_at\":\"2026-10-03T09:53:05.280Z\",\"occurred_at\":\"2026-10-03T09:37:25.975Z\",\"source\":\"crm\",\"source_id\":\"deal-1042\",\"version\":2,\"schema_version\":1,\"trashed_at\":null,\"read_only\":false,\"properties\":{\"name\":\"Renewal for Example Co\",\"amount\":12000,\"stage\":\"won\"}},\"metadata\":{\"item_id\":\"01a1011a-4902-76cf-a4a9-88e99c038c8d\",\"tags\":[\"renewal\",\"q4\",\"reviewed\"],\"extensions\":{}}}\n{\"item\":{\"id\":\"01a10119-55c0-77ac-9589-f7c48fa642b6\",\"type\":\"acme.deal\",\"state\":\"active\",\"tier\":\"library\",\"created_at\":\"2026-10-03T09:38:25.218Z\",\"updated_at\":\"2026-10-03T09:53:05.280Z\",\"last_activity_at\":\"2026-10-03T09:53:05.280Z\",\"occurred_at\":\"2026-10-03T09:38:25.218Z\",\"source\":\"crm\",\"source_id\":\"deal-1043\",\"version\":1,\"schema_version\":1,\"trashed_at\":null,\"read_only\":false,\"properties\":{\"name\":\"Pilot for Sample Ltd\",\"amount\":4500,\"stage\":\"won\"}},\"metadata\":{\"item_id\":\"01a10119-55c0-77ac-9589-f7c48fa642b6\",\"tags\":[\"reviewed\"],\"extensions\":{}}}\n{\"item\":{\"id\":\"01a10124-377f-7d3d-94ed-389b233f360b\",\"type\":\"acme.deal\",\"state\":\"active\",\"tier\":\"library\",\"created_at\":\"2026-10-03T09:48:40.507Z\",\"updated_at\":\"2026-10-03T09:53:05.280Z\",\"last_activity_at\":\"2026-10-03T09:53:05.280Z\",\"occurred_at\":\"2026-10-03T09:48:40.507Z\",\"source\":\"crm\",\"source_id\":\"deal-2001\",\"version\":1,\"schema_version\":1,\"trashed_at\":null,\"read_only\":false,\"properties\":{\"name\":\"Expansion for Demo Corp\",\"amount\":8000,\"stage\":\"lead\"}},\"metadata\":{\"item_id\":\"01a10124-377f-7d3d-94ed-389b233f360b\",\"tags\":[\"reviewed\"],\"extensions\":{}}}\n"