Folders

Update a folder

Updates a folder's title and settings at the version you read. Each setting you send replaces its value whole; omitted settings stay.

PATCH
/folders/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path parameters

id*string

The ID of the folder.

Header parameters

Idempotency-Key?string

A unique key that makes the request safe to retry. If you send the same request with the same key again, Marfa returns the first response and doesn't write again. A key belongs to the credential that sends it.

Lengthlength <= 255
X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body
version*integer

The version of the folder you read. If the folder has changed since, Marfa merges your change where nothing collides.

Range0 <= value
title?string

A new title for the folder.

Length1 <= length <= 500
query?

Which items the folder holds.

defaults?

What a new file takes where its frontmatter leaves a blank.

include?array<>

Gitignore patterns, relative to the folder's root, for the paths the folder takes. Empty or absent takes every path. A dot-led name is taken only if a pattern names it. Secrets and files a machine or editor writes for itself are never taken.

Itemsitems <= 1000
ignore?array<>

Gitignore patterns, relative to the folder's root, for the paths the folder leaves alone. They win over include.

Itemsitems <= 1000
first_placement?

Where an item made elsewhere first appears in the folder: a map from type identifier to a directory relative to the folder's root. The most specific matching type wins.

removal_threshold?

A removal waits to be confirmed when it takes more than files files and more than fraction of the folder's files, or more than ceiling files. Each scan or pull is judged on the files it removes.

full_pass_interval_seconds?integer

Seconds between the passes of a watch that read every file in the folder, in case the system missed a file event: 60 to 86400. Absent means 600.

Range60 <= value <= 86400
addition_threshold?

New files wait to be confirmed when a scan would add more than files files and more than fraction of the folder's files.

outside_query?string

What a machine does with a new file whose item the query would not hold. send makes it an item and keeps it in the folder, flagged unmatched. hold leaves it on the disk, not sent and with no item, until it matches the query or the setting is send. A file that already has an item is never affected. Absent means send.

Value in"send""hold"

Response body

About errors

Returns the updated folder and its metadata.

application/json
  1. response

An item with its metadata.

item*

The item.

metadata*

The item's metadata.

acknowledged?boolean

true when Marfa accepted a write and stored nothing: a create repeats an id you already created, its natural key matches a trashed item, or an update or upsert leaves the item as it is, so item is at the version it holds. Absent otherwise.

  • validation_error: a setting is malformed or undeclared (details.errors[0].path or details.unknown_body_fields names it).
  • missing_required_field: version is missing.
  • unknown_type: a setting's type is unknown.
  • invalid_properties: defaults.properties has a whole number a 64-bit float can't keep.
  • invalid_id: the ID is invalid.
  • invalid_transition: the folder is revoked.
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: you don't have write on system.folder.
application/json
  1. response

An error response.

error*

What went wrong.

  • item_not_found: no system.folder has this ID.
application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

  • version_conflict: a setting you sent has changed since version. conflicting_fields names it.
  • ancestor_unavailable: Marfa holds no snapshot of version to merge from.
application/json
  1. response

A stale write whose changes collide: the item now, the item at your version, and what collided.

error*

What went wrong.

current*

The item as it stands now.

ancestor*

The item at the version you sent.

conflicting_fields*array<string>

The properties, and fields such as tier, that both your write and a write since your version changed.

merge_policy*

The merge policy of the item's type, which conflict=auto resolves by.

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.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

  • idempotency_contract_changed: the first response was made under another contract version, so Marfa can't replay it. The write isn't repeated.
  • idempotency_key_reused: the key was first used for a different request. Nothing is written.
  • idempotency_result_not_retained: the first response was too large to keep, so Marfa can't replay it. The write isn't repeated.
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.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

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 PATCH 'http://localhost:8600/folders/string' \  -H 'Content-Type: application/json' \  -d '{  "version": 0}'
About errors
{  "item": {    "id": "01a10122-54e3-7447-9e6f-91e7d99f361f",    "type": "system.folder",    "state": "active",    "tier": "library",    "created_at": "2026-10-03T09:57:30.610Z",    "updated_at": "2026-10-03T09:58:30.928Z",    "last_activity_at": "2026-10-03T09:58:30.928Z",    "occurred_at": "2026-10-03T09:57:30.610Z",    "source": "crm",    "version": 2,    "schema_version": 0,    "trashed_at": null,    "read_only": false,    "properties": {      "title": "Open deals",      "query": {        "types": [          "acme.deal"        ]      },      "defaults": {        "type": "acme.deal"      }    }  },  "metadata": {    "item_id": "01a10122-54e3-7447-9e6f-91e7d99f361f",    "tags": [],    "extensions": {}  }}