Folders

Create a folder

Creates a folder: a system.folder item whose properties are the settings every machine bound to the folder shares. The item endpoints can't write one.

POST
/folders

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

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
title*string

The folder's title.

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 new folder, a system.folder item, 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, such as a system.* type, a .. placement or a backref filter. details.errors[0].path or details.unknown_body_fields names it.
  • missing_required_field: title 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.
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.

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.

instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.

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.

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 POST 'http://localhost:8600/folders' \  -H 'Content-Type: application/json' \  -d '{  "title": "string"}'
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:57:30.610Z",    "last_activity_at": "2026-10-03T09:57:30.610Z",    "occurred_at": "2026-10-03T09:57:30.610Z",    "source": "crm",    "version": 1,    "schema_version": 0,    "trashed_at": null,    "read_only": false,    "properties": {      "title": "Deals",      "query": {        "types": [          "acme.deal"        ]      },      "defaults": {        "type": "acme.deal"      }    }  },  "metadata": {    "item_id": "01a10122-54e3-7447-9e6f-91e7d99f361f",    "tags": [],    "extensions": {}  }}