API reference
Every operation in Marfa's API, with its parameters, request body, answers and error codes.
Everything an app, a script or a connector does with an instance goes through its HTTP API, and the CLI, the TypeScript SDK and the Swift SDK send the same requests. Each operation has a page generated from the API description, so it matches the server.
Operations by area
The operations fall into five areas: Data (items and everything attached to them), Changes (following what happens to them), Access (keys, apps and the owner), Connectors (what the instance keeps for each connector) and the Instance itself. Each area holds a group for each kind of thing an operation acts on, with its operations by method and path, in the order the sidebar shows them.
Items20
The records Marfa stores, each of a type, and the ways to read and change them.
- POST
/items - GET
/items/ {id} - GET
/items - PATCH
/items/ {id} - DELETE
/items/ {id} - POST
/items/ trash-preview - POST
/items/ trash - POST
/items/ {id}/ restore - POST
/items/ {id}/ purge - POST
/items/ {id}/ transition - GET
/items/ {id}/ versions - POST
/items/ lookup - POST
/items/ titles - POST
/items/ bulk-get - POST
/items/ counts - POST
/items/ bulk - GET
/items/ stats - GET
/items/ summaries - GET
/occurrences - POST
/items/ tombstones
Trash2
Items in the trash: list them, move an item in, and restore, purge or empty them.
Bulk actions3
One change applied to every item a filter matches, run as a job you can follow and cancel.
Metadata4
An item's tags and extensions together, and the tags in use.
Extensions4
JSON objects attached to an item, one per namespace.
Tables7
The rows an item holds in the tables its type declares.
Edges8
Typed, directed relationships between items.
Search1
Full-text search across items.
Types9
The types items can have: those Marfa ships and those registered on this instance.
Edge types3
The types edges can have, each with its cardinality and cascade rule.
Blobs8
Bytes stored by content hash, and the stores that hold them.
Views4
Saved lists of items with their sort and grouping, held as system.view items.
Event stream1
Changes to items, table rows and edges, streamed as they happen.
Webhooks8
Changes sent to a URL you choose, and each delivery's record. Keys and apps use these endpoints; the owner's browser session can't.
API keys5
The keys that authenticate requests to this instance, and the permissions each holds.
Apps8
Apps that register as OAuth clients, how they sign in, and the access the owner grants them.
Owner5
The instance's owner and their profile.
Sign-ins and passkeys8
The browsers, apps and keys that can reach the instance, and the owner's passkeys and password.
Connectors7
Processes outside the server that read and write on your behalf, with their heartbeats and runs.
Connector state8
What the instance keeps for a connector's source: its hold, its state document and its agreements.
Inbound webhooks6
Addresses where a service sends requests to a connector, and the deliveries Marfa stores for it.
Sources3
The codes items carry to say what wrote them, and the name and mark each is shown by.
Instance7
The instance itself: what it is and how it's configured.
Health and maintenance9
How the instance is doing: its health, what needs attention, its metrics, its audit log, its housekeeping jobs and its updates.
Export and restore6
Export the instance's data, and restore it from an archive.
Folders6
A folder's settings, held as a system.folder item.
Send a request
Send each request to your instance's address, such as http://localhost:8600 for one on your own machine. Almost every operation takes a credential in the Authorization header: a key, which begins marfa_k1_, or an app's access token, which begins marfa_at_. Access explains both, and Manage keys shows how to make a key.
A request body is JSON, sent with Content-Type: application/json, except Upload a blob, which takes a file's bytes. This request makes a file item from a picture already uploaded:
POST /items HTTP/1.1
Host: localhost:8600
Authorization: Bearer <key>
Content-Type: application/json
{ "type": "core.file", "properties": { "title": "Tide chart", "blob_ref": "sha256:2bab1df2e7e3d2614e09a7dcb7f4adbf67c96cb6efaa0f1068ca19caed5610c8", "mime_type": "image/png" } }Marfa answers 201 Created with the new item and its metadata. It adds the blob's size itself:
{
"item": {
"id": "01a1f14c-4290-758b-9864-b91eedc89488",
"type": "core.file",
"state": "active",
"tier": "library",
"created_at": "2026-11-19T00:54:29.264Z",
"updated_at": "2026-11-19T00:54:29.264Z",
"last_activity_at": "2026-11-19T00:54:29.264Z",
"occurred_at": "2026-11-19T00:54:29.264Z",
"source": "laptop",
"version": 1,
"schema_version": 0,
"trashed_at": null,
"read_only": false,
"properties": {
"blob_ref": "sha256:2bab1df2e7e3d2614e09a7dcb7f4adbf67c96cb6efaa0f1068ca19caed5610c8",
"mime_type": "image/png",
"title": "Tide chart",
"size_bytes": 69
},
"edges": {}
},
"metadata": { "item_id": "01a1f14c-4290-758b-9864-b91eedc89488", "tags": [], "extensions": {} }
}A refusal answers with an error object instead, as Errors explains.
Rules every operation follows
Marfa stores typed records, called items, and the edges between them. This reference describes its HTTP API.
Authentication
Send a credential in the Authorization header as Bearer <token>: an API key (marfa_k1_…) or the access token of an app someone signed in to (marfa_at_…). In this reference, you means the credential that sends the request.
Recent sign-in
Restoring an archive or a backup, moving the sign-in address, changing allow_private_addresses and changing where files and backups go (backup_path and the object_store_ settings other than the access key ID and the secret) also need the owner to have signed in within the last fifteen minutes. An app's access token whose owner signed in longer ago is answered 401 insufficient_user_authentication with WWW-Authenticate: Bearer error="insufficient_user_authentication", max_age="900", as RFC 9470 describes. Send the owner through GET /oauth/authorize with max_age=900: Marfa asks them to sign in again, and the tokens the code leads to carry the new sign-in. A refreshed token keeps the time of the sign-in it came from. An API key has no sign-in to renew, so it is refused these acts with 403 app_sign_in_required, and the private local command makes them without one.
Local command
An operation marked x-marfa-local-command also answers the private local listener: a Unix socket that only the account running the instance can open. The connection is the proof, so the request carries no credential, and no security scheme here describes it. The marfa command line reaches it with --socket.
Permissions
Your credential reads and writes only the types its permissions reach. If you ask by ID for an item whose type you can't read, Marfa answers as if the item doesn't exist. An edge appears in a response only if you can read both its edge type and the type of the item it starts from.
Pagination
A list returns one page at a time, as { "data": [...], "next_cursor": "..." }. To get the next page, send next_cursor back as cursor. The last page has next_cursor: null. A page can be short or empty and still have more after it, so stop only when next_cursor is null. A list that can't page answers { "data": [...] } alone.
Answers
An operation that returns one object returns it bare, and wraps it only where the answer holds more than the object. A delete answers 200 with { "ok": true } once the thing is gone, and 200 with the object where the object stays in a new state. No operation answers 204.
Query parameters
Every operation refuses a query parameter it doesn't recognize with 400 validation_error, so a misspelled filter can't silently return everything. A boolean parameter is true or false, and anything else, 1 and yes included, is a 400 validation_error. The edge[<type>] and backref[<type>] filters on GET /items and GET /items/stats are recognized for any type. Marfa ignores any parameter that starts with _, so use that prefix for a parameter of your own, such as a cache buster. The OAuth operations GET /oauth/authorize, POST /oauth/token, POST /oauth/revoke and POST /oauth/device-authorization ignore a parameter they don't recognize, as RFC 6749 requires.
Errors
An error answers { "error": { "code": "...", "message": "...", "details": {} } }. Use code in your logic: each operation lists the codes it can return, and the X-Error-Code header repeats it. message is for people and can change. A version conflict also carries the item or edge as it stands now, in current, so you can merge and try again.
The OAuth operations under /oauth/ answer their own errors in the shape their RFCs define, { "error": "...", "error_description": "..." }, with no X-Error-Code. A refusal every operation shares, such as 412 or 429, keeps the shape above.
Idempotency
A write that takes an Idempotency-Key header is safe to retry. Send the same request with the same key, and Marfa returns the first response, with Idempotency-Replayed: true, and doesn't write again. A key belongs to the credential that sends it. While the first request with a key is still running, a repeat returns 409 idempotency_key_in_flight and writes nothing, so retry it. Reusing a key for a different request returns 422 idempotency_key_reused. Repeating a request after Marfa moves to another contract version returns 422 idempotency_contract_changed, with the first response's status in details.original_status, and doesn't write again.
Request bodies
A body is JSON, sent with Content-Type: application/json. A request that doesn't send its body as JSON returns 400 validation_error and changes nothing, even if it has no body at all. The exceptions are POST /blobs, which takes the bytes of a blob, and POST /restore, which takes an archive. POST /oauth/token, POST /oauth/revoke and POST /oauth/device-authorization take a form (application/x-www-form-urlencoded), as their RFCs define. POST /oauth/register takes JSON, and answers a request that isn't JSON with 400 invalid_client_metadata.
Time
Every time is UTC, written as 2026-10-03T09:30:00.000Z. A time field is named for what happened, such as created_at. A filter on a time field pairs _after and _before, and both leave out the time you give, except updated_after, which includes it so that nothing changed at the same moment is skipped. GET /occurrences takes a window, from and to, instead.
Event stream
GET /events sends each change as a frame whose id: is its event ID, in the order Marfa made the changes. To resume, reconnect with the last ID you received as Last-Event-ID, under any type or edges filter: Marfa replays what you missed, then sends stream_live. Marfa reads your credential again before each batch of frames and every 30 seconds: you receive only what it can read now, and a credential that's revoked or expired ends the stream, so reconnect with a current one. Ignore lines that start with :.
Web pages
A web page can connect from a browser with no setup. POST /oauth/register and the discovery documents answer any origin, so the page registers itself, then opens the authorization endpoint in a window for the owner to approve. Once the owner approves it, the origin of each redirect URI it registered may call every operation from a browser. Send the access token in Authorization: no response allows a browser's credentials.
Every response
Every response carries X-Marfa-Contract, the version of this contract, which is also this document's version. Every response also carries X-Request-ID, which identifies the request if you report a problem. Send X-Marfa-Contract on every request but a read of / and of /health, naming the contract version your client was built for. A request that names another version, or a value that is not a whole number, returns 412 contract_mismatch and changes nothing. A request that names none is served.