# Marfa

> Marfa is a server you run yourself that holds one person's data in one place, in types every app understands, so the apps, scripts and AI agents they allow can read and write it through one HTTP API.

These docs cover what Marfa is, running an instance, building apps, connectors and agents on it, and the API. Each written page below links to its Markdown copy, and the same address without `.md` is the HTML. A request for a page's address with `Accept: text/markdown` gets the Markdown copy too. `https://docs.marfa.so/docs-map.md` is this index with HTML links.

`https://docs.marfa.so/llms-full.txt` holds the written pages in one file. It leaves out the API operations and the changelog. The changelog is long, and an operation's Markdown copy holds only its title and description, so each API operation links to its HTML page, which holds its full request and response. The API description with every operation is `openapi.json` in https://github.com/withmarfa/marfa. The changelog's Markdown copy is `https://docs.marfa.so/changelog.md`. The docs MCP server at `https://docs.marfa.so/mcp` searches every page, including the operations and the changelog, and its `docs_fetch` tool reads one page.

## Overview

### Get started

- [Overview](https://docs.marfa.so/overview.md): Marfa is a shared data layer for your apps, and you run it yourself.
- [Introduction](https://docs.marfa.so/introduction.md): What Marfa is, what you can do with it, what it isn't, and where it runs.
- [Quickstart](https://docs.marfa.so/quickstart.md): Start Marfa on your own computer, claim it, make a key, and write and change your first note.

### Concepts

- [How Marfa works](https://docs.marfa.so/how-marfa-works.md): The parts of Marfa and how they fit together, from the instance that holds your data to the apps, devices and connectors that reach it.
- [Items and types](https://docs.marfa.so/items-and-types.md): An item is one record, such as a note or a task, and its type says what the item holds. Everything else in Marfa builds on these two ideas.
- [Properties, metadata and edges](https://docs.marfa.so/properties-metadata-and-edges.md): An item's data lives in four places, properties, tags, extensions and edges, and each suits a different kind of information.
- [Versions](https://docs.marfa.so/versions.md): How an item's version counts its changes, so that two apps writing the same item never silently overwrite each other.
- [Files](https://docs.marfa.so/files.md): How Marfa keeps a file's bytes once, however many items name them, who may read them, and where the copies live.
- [Access](https://docs.marfa.so/access.md): Who can act on an instance, and how a key or an app is limited to the data and operations it needs.
- [Events and webhooks](https://docs.marfa.so/events.md): How an app learns what changed in an instance, by reading the event stream or by receiving webhooks.
- [Devices](https://docs.marfa.so/devices.md): How an app keeps a copy of your data on a phone or a Mac, works without a connection, and sends its changes when it can.
- [Connectors](https://docs.marfa.so/connectors.md): How a connector brings records from another service into Marfa, and what the instance keeps so it can stop and resume safely.
- [Glossary](https://docs.marfa.so/glossary.md): The words Marfa uses, each with one meaning, and where to read more.

### AI tools

- [Docs MCP server](https://docs.marfa.so/docs-mcp-server.md): Connect an AI agent to these docs over MCP, so it searches and reads the current pages instead of working from memory.
- [Docs as Markdown](https://docs.marfa.so/docs-as-markdown.md): Read these docs from a terminal, as JSON or as Markdown, with no MCP, credential or Marfa instance needed.

## Guides

### Tutorials

- [Build an app with Swift](https://docs.marfa.so/guides/swift-app.md): Build an iOS and macOS app that lists your notes, keeps working without a connection, and stays in step with your instance.
- [Build a connector](https://docs.marfa.so/guides/connector.md): Make a working connector from the kit's template, run it against a stand-in service, and watch it follow changes and report a failure.

### Build apps and agents

- [Authenticate](https://docs.marfa.so/guides/authenticate.md): Send a key with data requests, or connect an app with OAuth so the owner approves its access.
- [Use Marfa with AI agents](https://docs.marfa.so/guides/ai-agents.md): Give an AI agent, such as Claude Code or Codex, a key of its own, so it can work with your notes, tasks and files and nothing else.
- [Connect a web page](https://docs.marfa.so/guides/connect-a-web-page.md): Let a page in a browser register itself with an instance, get the owner's approval in a small window, and read the owner's data with the token it receives.
- [Define a type](https://docs.marfa.so/guides/define-a-type.md): Register a type for items no shipped type fits, then change it as your app grows, or delete it.
- [List, filter and search](https://docs.marfa.so/guides/list-filter-search.md): Read the items you need from an instance, a page at a time, narrowed by type, tags and properties, or found by the words they hold.
- [Read a view offline](https://docs.marfa.so/guides/read-a-view.md): Read a saved view's items, groups, counts and sums from a device's working copy.
- [Write safely](https://docs.marfa.so/guides/write-safely.md): Change an item without overwriting someone else's change, handle a conflict when one happens, and retry a write without making it twice.
- [Keep a copy in sync](https://docs.marfa.so/guides/keep-in-sync.md): Follow an instance's event stream from a cursor, so a copy of your data stays current and picks up where it stopped after a break.
- [Handle files](https://docs.marfa.so/guides/handle-files.md): Upload a file's bytes, make the item that names them, download them, hand out a link that expires, and replace them.
- [Receive webhooks](https://docs.marfa.so/guides/receive-webhooks.md): Register a webhook, check that each delivery came from your instance, and handle repeats, deliveries that arrive out of order, retries and failed deliveries.
- [Sync a folder](https://docs.marfa.so/guides/sync-a-folder.md): Keep a directory on your Mac and a set of items in step, so each note is a Markdown file you can edit in any app.
- [Keep folders running](https://docs.marfa.so/guides/keep-folders-running.md): Keep every folder on your computer in step with one watch, start it at login, and work on a folder's files while it runs.
- [Folder safeguards](https://docs.marfa.so/guides/folder-safeguards.md): What removes a file or an item in a folder, what a folder refuses to touch, and how to tell when a push has stopped.

### Build connectors

- [Pull and push](https://docs.marfa.so/guides/connector-pull-and-push.md): Write a vendor's records into Marfa as items, notice what people change there, and carry those changes back to the vendor.
- [Receive vendor webhooks](https://docs.marfa.so/guides/connector-webhooks.md): Give a vendor an address to post webhooks to, then check each delivery came from the vendor, act on it and mark it handled.
- [Holds and retries](https://docs.marfa.so/guides/connector-holds-and-retries.md): Keep one process of a connector writing at a time, keep its place between runs, and send a failed request again without harm.

### Run Marfa

- [Install with the CLI](https://docs.marfa.so/guides/install.md): Take a Mac or Linux machine with Docker to an instance ready to claim, with one command.
- [Deploy](https://docs.marfa.so/guides/deploy.md): Run an instance you keep, with one command or by hand, with storage that survives a restart, two secrets you back up and an address your devices can reach.
- [Sign in as the owner](https://docs.marfa.so/guides/sign-in-as-the-owner.md): Sign in to the owner's pages with a password or a passkey, confirm it's you before a sensitive change, open each page from Home, and recover a lost password.
- [Settings](https://docs.marfa.so/guides/settings.md): Set an instance’s startup environment and change its name, data rules and operating policies while it runs.
- [Send telemetry](https://docs.marfa.so/guides/telemetry.md): Send an instance's traces and logs to an OpenTelemetry endpoint, its errors to PostHog, and a notice or a heartbeat to a URL you choose.
- [Manage keys](https://docs.marfa.so/guides/manage-keys.md): Give a script or service a key that reaches only what it needs, then narrow, expire, rotate or revoke it.
- [Run a connector](https://docs.marfa.so/guides/run-a-connector.md): Build a connector from the marfa-connectors repository, give it a key of its own, and run it once or on a schedule.
- [Create a Google Cloud project for Google connectors](https://docs.marfa.so/guides/google-project.md): Create a Google Cloud project of your own, publish it, and sign in once so every Google connector can read your account.
- [Back up and restore](https://docs.marfa.so/guides/back-up-and-restore.md): Copy an instance's data directory and secrets so you can bring it back after a failed disk or a lost machine.
- [Export and restore an archive](https://docs.marfa.so/guides/export-and-restore.md): Export your items, edges, types and files to an archive, and restore it into the same instance or another, such as a new build.
- [Upgrade](https://docs.marfa.so/guides/upgrade.md): Check a new build against your database while keeping a way back to the build that wrote it.
- [Housekeeping](https://docs.marfa.so/guides/housekeeping.md): See the work an instance does on itself, read what each housekeeping job last did, and run one now.
- [Audit log](https://docs.marfa.so/guides/audit-log.md): Find out who changed what on an instance, and when, by reading and filtering its audit log.
- [Troubleshooting](https://docs.marfa.so/guides/troubleshooting.md): The cause and the fix for the problems people meet first, found by the message Marfa shows.

## Catalog

- [Catalog](https://docs.marfa.so/catalog.md): Every type, edge type, event and permission Marfa ships, with the fields and values each one has.
- [Items](https://docs.marfa.so/catalog/items.md): The fields every item has, whatever its type, and the fields search reads.
- [Edges](https://docs.marfa.so/catalog/edges.md): The edge types every instance ships, and what each one carries.
- [Events](https://docs.marfa.so/catalog/events.md): The events that streams and webhooks deliver, and the fields each one carries.
- [Permissions](https://docs.marfa.so/catalog/permissions.md): The permissions a credential can hold, and its access levels for types, edge types and profile fields.

### Types

- Core types
  - [Bookmark](https://docs.marfa.so/catalog/bookmark.md): Content you captured from elsewhere: a saved URL, a highlight, an excerpt, a clipped paragraph.
  - [Entity](https://docs.marfa.so/catalog/entity.md): Any named entity: a person, a company, a band, a team, a charity, a brand, a school or a place. core.entity.person and core.entity.place narrow it.
  - [Event](https://docs.marfa.so/catalog/event.md): Something that happens at a time.
  - [File](https://docs.marfa.so/catalog/file.md): A file or binary reference: the generic fallback for non-media files.
  - [Highlight](https://docs.marfa.so/catalog/highlight.md): A user's engagement with content: the highlighted passage plus optional annotation. The canonical relationship (what was highlighted) is carried by a references edge; the moment of highlighting is the item's own occurred_at.
  - [Media](https://docs.marfa.so/catalog/media.md): Content produced by someone that the user engages with: a film, podcast, book, article, song, show.
  - [Message](https://docs.marfa.so/catalog/message.md): A light, cross-platform message. Threading is edge-based via in-thread; reply trees via parent-of. Tool-specific richness lives in app namespaces.
  - [Note](https://docs.marfa.so/catalog/note.md): Text content you created.
  - [Task](https://docs.marfa.so/catalog/task.md): Something to be done.
- System types
  - [Connection](https://docs.marfa.so/catalog/connection.md): An OAuth client this user has authorized, written when the user approves the client's consent or device sign-in. kind is app. Lifecycle bounded to active | revoked. Has no tier.
  - [Folder](https://docs.marfa.so/catalog/folder.md): A folder's settings, held here and shared by every machine bound to the folder; each machine chooses only the directory. The settings are written only through /folders: created, changed at a version, and revoked. Lifecycle bounded to active | revoked. Has no tier.
  - [View](https://docs.marfa.so/catalog/view.md): A saved list of items, held here and shared by every app: which items, and how each layout shows them. Written only through /views: created, changed at a version, and deleted, which removes it at once with no trash. Lifecycle bounded to active | revoked. Has no tier.
- [Type rules](https://docs.marfa.so/catalog/your-own-types.md): The rules a type you register must meet: its identifier, fields, parent, roles, merge policy and retention policy.
- [Field kinds](https://docs.marfa.so/catalog/field-kinds.md): The kinds of value a type's field can hold, and what Marfa accepts for each.

## Reference

### SDKs and CLI

- [TypeScript SDK](https://docs.marfa.so/typescript-sdk.md): Call your instance from TypeScript or JavaScript with a client that knows every operation, its parameters and its answers.
- [Swift SDK](https://docs.marfa.so/swift-sdk.md): Give an iOS or macOS app a working copy of your instance that reads offline, queues its writes and keeps itself current.
- [CLI](https://docs.marfa.so/cli.md): Install the marfa program, see how it finds your instance and credential, and look up its options and exit codes.
- [Folder watch record](https://docs.marfa.so/folder-watch-record.md): The file a running folder watch keeps for other programs on the computer, and how to read whether folders are syncing.

### HTTP API

- [API reference](https://docs.marfa.so/api-reference.md): Every operation in Marfa's API, with its parameters, request body, answers and error codes.
- [Errors](https://docs.marfa.so/api-reference/errors.md): The shape of a refusal, what it tells you, which refusals to retry, and every code Marfa answers.

### Items

- [Create an item](https://docs.marfa.so/api-reference/items/createItem): Creates an item. If `source_id` matches an existing item under the same source, updates that item instead. Repeating an `id` you already created returns the stored item with `acknowledged: true` and writes nothing.
- [Get an item](https://docs.marfa.so/api-reference/items/getItem): Returns an item with its metadata and outbound edges. Use `include` to add its inbound edges, the items at the other end of its edges, or its version history in the same call.
- [List items](https://docs.marfa.so/api-reference/items/listItems): Returns a page of the items you can read that match the filters. System items are left out unless you ask for them with `include=system`. Use `include` to add edges, metadata or extensions to each item.
- [Update an item](https://docs.marfa.so/api-reference/items/updateItem): Updates an item's properties, tier, own time, natural key or edges. Send the `version` you read; stale writes can merge unless `version_match` is `exact`. To change its type, send `type` with `retype: true`.
- [Trash an item](https://docs.marfa.so/api-reference/items/deleteItem): Moves the item, and every item a cascading edge such as `parent-of` reaches, to the trash. You can restore them until the retention window ends. Marfa then purges them.
- [Restore an item](https://docs.marfa.so/api-reference/items/restoreItem): Restores a trashed item to `active`, along with every item its trash took through a cascading edge such as `parent-of`. Items that were already in the trash before then stay there.
- [Purge an item](https://docs.marfa.so/api-reference/items/purgeItem): Permanently deletes a trashed item with its edges, metadata and extensions. Requires `items.purge` and write on the item's type. Marfa keeps a tombstone of the item's link and natural key, which `POST /items/lookup` reads.
- [Change an item's state](https://docs.marfa.so/api-reference/items/transitionItem): Moves the item to `active`, `archived` or `trashed`. Moving to `trashed` deletes the item as `DELETE /items/{id}` does, and moving from `trashed` to `active` restores it as `POST /items/{id}/restore` does.
- [List item versions](https://docs.marfa.so/api-reference/items/listItemVersions): Returns a page of the item's version snapshots, oldest first. Marfa thins older snapshots over time, so the history can have gaps.
- [Look up items](https://docs.marfa.so/api-reference/items/lookupItems): Finds items, in any state, by link, by natural key or by ID, and returns the tombstones that purges left for those keys. Name exactly one of `links`, `source` with `source_ids`, or `ids`, with at most 500 values.
- [Get items in bulk](https://docs.marfa.so/api-reference/items/bulkGetItems): Returns up to 100 items by ID in one call, in the order you named them, each once. Items you can't read, trashed items and IDs that name nothing are left out.
- [Upsert items in bulk](https://docs.marfa.so/api-reference/items/bulkUpsertItems): Creates or updates up to 5,000 items in one call, matching existing items on `(source, source_id)`. The batch is atomic by default: one failed entry rolls it all back. Returns each entry's outcome.
- [Get item counts](https://docs.marfa.so/api-reference/items/getItemStats): Returns item counts by state or type using the filters of `GET /items`. Counts every state unless you name one. The owner can use their browser session.
- [List item summaries](https://docs.marfa.so/api-reference/items/listItemSummaries): Returns item names, types, versions, sources and creation times, newest first. Only the owner or a local command can use this operation. Trashed and system items are excluded.
- [List event occurrences](https://docs.marfa.so/api-reference/items/listOccurrences): Returns the events that overlap a time window, with each recurring event expanded into one entry per occurrence. Marfa computes occurrences when you read them and doesn't store them.
- [Settle tombstones](https://docs.marfa.so/api-reference/items/settleTombstones): Settles tombstones, moving their `settled_at` later, never earlier, and returns them. A connector calls it after changing the vendor's copy to carry out a purge, so that change doesn't bring the item back as a new row.

### Trash

- [List the trash](https://docs.marfa.so/api-reference/trash/listTrash): Returns a page of trash summaries, newest creation first, without item content. Only the owner or a local command can use this operation.
- [Trash an item by summary](https://docs.marfa.so/api-reference/trash/trashItemSummary): Moves the item and its cascading children to the trash. Returns only a summary. Requires the version from the listing.
- [Restore an item by summary](https://docs.marfa.so/api-reference/trash/restoreItemSummary): Restores the item and the children its trash took. Returns only a summary. Requires the version from the listing.
- [Purge an item by summary](https://docs.marfa.so/api-reference/trash/purgeItemSummary): Purges one item, deleting it permanently, if it is still in the trash at the listed version. Returns only a summary.
- [Empty the trash](https://docs.marfa.so/api-reference/trash/emptyTrash): Empties one page of the trash: deletes up to 200 items permanently if their state and version still match. Returns partial results and a continuation cursor. Items trashed during the operation may remain.

### Bulk actions

- [Apply a bulk action](https://docs.marfa.so/api-reference/bulk-actions/applyBulkAction): Applies one action to every item that matches a filter: change state, purge, update tags, tier, properties or own time. It matches only items you can write. With `dry_run: true` it returns the matched IDs; otherwise it queues a bulk-action job.
- [Get a bulk-action job](https://docs.marfa.so/api-reference/bulk-actions/getBulkActionJob): Returns a bulk-action job's status and counts, and its `result` once it has finished. Only the credential that queued the job, or the holder of `instance.read`, can read it.
- [Cancel a bulk-action job](https://docs.marfa.so/api-reference/bulk-actions/cancelBulkActionJob): Cancels a bulk-action job and returns it. Items the job already processed stay processed. A job that has already finished is left as it is.

### Metadata

- [Get item metadata](https://docs.marfa.so/api-reference/metadata/getItemMetadata): Returns an item's metadata: its tags and the extension namespaces you can read. To read metadata for many items, use `include=metadata` on `GET /items`.
- [Replace an item's tags](https://docs.marfa.so/api-reference/metadata/replaceItemMetadata): Replaces the item's tags with the ones you send and returns its metadata. An empty list clears all tags.
- [Add tags to an item](https://docs.marfa.so/api-reference/metadata/addItemTags): Adds tags to the item and returns its metadata. A tag the item already has isn't added twice.
- [Remove a tag from an item](https://docs.marfa.so/api-reference/metadata/removeItemTag): Removes one tag from the item and returns its metadata. Removing a tag the item doesn't have changes nothing and succeeds.
- [List tags](https://docs.marfa.so/api-reference/metadata/listTags): Returns every tag in use on the active items you can read, with the number of items that carry it. Sorted by count, highest first, then by tag.

### Extensions

- [Get an extension namespace](https://docs.marfa.so/api-reference/extensions/getItemExtension): Returns the data in one extension namespace on the item, or `data: null` if the item has none there.
- [List extension namespaces](https://docs.marfa.so/api-reference/extensions/listItemExtensions): Returns the extension namespaces on the item that you can read, each with its data.
- [Replace an extension namespace](https://docs.marfa.so/api-reference/extensions/replaceItemExtension): Replaces the data in one extension namespace on the item, and returns the namespaces you can read. Marfa announces `metadata.changed`.
- [Delete an extension namespace](https://docs.marfa.so/api-reference/extensions/deleteItemExtension): Removes one extension namespace from the item, and returns the namespaces left that you can read. Deleting a namespace that isn't there still succeeds and announces `metadata.changed`.

### Edges

- [Create an edge](https://docs.marfa.so/api-reference/edges/createEdge): Creates an edge between two existing items. After any `source_version` precondition passes, repeating an `id` you already created returns the stored edge with `acknowledged: true` and writes nothing.
- [Get an edge](https://docs.marfa.so/api-reference/edges/getEdge): Returns one edge by its ID. Use it when you hold only an edge's ID, such as from an event.
- [List edges](https://docs.marfa.so/api-reference/edges/listEdges): Returns the edges you can read, newest first, whether or not the items they join are in the trash. A deleted edge doesn't appear: `GET /events` reports deletions. Nor does an edge whose source item `source_filter` leaves out.
- [Update an edge](https://docs.marfa.so/api-reference/edges/updateEdge): Merges properties into an edge, or moves one of its ends, and returns it. A property you leave out stays. Sending `null` stores a null, so you can add properties but not remove them.
- [Delete an edge](https://docs.marfa.so/api-reference/edges/deleteEdge): Deletes an edge and leaves the items it joined as they are. The edge type's `cascade_on_delete` applies when you delete an item, not an edge.
- [Upsert edges in bulk](https://docs.marfa.so/api-reference/edges/bulkUpsertEdges): Creates or updates up to 5,000 edges in one call, matching existing edges on `(source_id, target_id, edge_type)`. The batch is atomic by default: one failed entry rolls it all back. Returns each entry's outcome.
- [List outbound edges](https://docs.marfa.so/api-reference/edges/listItemEdges): Returns the edges that start at an item. An item in the trash still lists its edges. If `source_filter` leaves the item out, none of its edges appear here. `GET /items/{id}/backrefs` lists the edges that point at it.
- [List inbound edges](https://docs.marfa.so/api-reference/edges/listItemBackrefs): Returns the edges that point at an item. An item in the trash still lists its edges. An edge whose source item `source_filter` leaves out doesn't appear here, whatever the source of this item. `GET /items/{id}/edges` lists the edges that start at it.

### Search

- [Search items](https://docs.marfa.so/api-reference/search/searchItems): Returns a page of the items you can read whose text properties or tags match `q`, ranked by BM25 relevance, with ties ordered by item ID.

### Types

- [Register a type](https://docs.marfa.so/api-reference/types/registerType): Registers a type under the `app.*`, `user.*` or `<publisher>.*` namespace and returns it. Name a `parent` to inherit its fields.
- [Get a type](https://docs.marfa.so/api-reference/types/getType): Returns a type's schema, with the fields and policies it inherits from its ancestors. Every credential reads any type, whatever its type map reaches.
- [List types](https://docs.marfa.so/api-reference/types/listTypes): Returns every type on this instance: those Marfa ships and those registered through `POST /types`. Every credential reads the whole list, whatever its type map reaches.
- [Replace a type](https://docs.marfa.so/api-reference/types/replaceType): Replaces a registered type's whole schema and returns it. A field you leave out is removed, but items keep their values for it. `metadata.types:write` alone can add optional fields and change `label`, `description`, `display_hints` or `version`.
- [Delete a type](https://docs.marfa.so/api-reference/types/deleteType): Deletes an unused type. A key can use `force=true` to keep existing items without their type; new writes then fail until it is registered again. A recent owner session or local command can remove only unused types.
- [Normalize a type definition](https://docs.marfa.so/api-reference/types/normalizeType): Normalizes a candidate definition and returns its declared form, the registered declared definition and the registered resolved definition. It does not register or replace a type.

### Edge types

- [Register an edge type](https://docs.marfa.so/api-reference/edge-types/registerEdgeType): Registers an edge type and returns it. With `evolve_constraints: true`, widens a registered type's endpoint constraints without changing its edges. An edge type can't extend another.
- [List edge types](https://docs.marfa.so/api-reference/edge-types/listEdgeTypes): Returns every edge type on this instance: those Marfa ships and those registered through `POST /edge-types`. Every credential reads the whole list, whatever its edge map reaches.
- [Delete an edge type](https://docs.marfa.so/api-reference/edge-types/deleteEdgeType): Deletes a registered edge type. With `force=true`, edges of the type stay and keep naming it.

### Blobs

- [Upload a blob](https://docs.marfa.so/api-reference/blobs/uploadBlob): Stores the request body as a blob and returns its `sha256:` hash. Uploading bytes Marfa already holds returns the same hash, and there is no size limit. To read the blob back, first write its hash into an item, edge or extension.
- [Download a blob](https://docs.marfa.so/api-reference/blobs/downloadBlob): Returns the bytes of a blob, from whichever store holds them, as a download. Send one `Range` to get part of it. `HEAD` returns the headers alone.
- [Get a blob URL](https://docs.marfa.so/api-reference/blobs/getBlobUrl): Returns a URL that serves the blob's bytes without a credential, and `expires_in`, the seconds until it stops working. The URL keeps working for that time even if you revoke your credential.
- [List a blob's copies](https://docs.marfa.so/api-reference/blobs/listBlobCopies): Returns the stores that hold a copy of the blob, with when each copy was recorded and when a check last found it intact.
- [Delete one copy of a blob](https://docs.marfa.so/api-reference/blobs/deleteBlobCopy): Deletes one store's copy of a blob, and Marfa's record of it. Requires `blobs.manage`.
- [List blob stores](https://docs.marfa.so/api-reference/blobs/listBlobStores): Returns every store the instance has attached, including any it has since detached, and `min_copies`, the fewest live copies Marfa keeps of a blob. Requires `instance.read`.
- [List orphaned blobs](https://docs.marfa.so/api-reference/blobs/listBlobOrphans): Returns the blobs that nothing references, as the last run of the `blob-orphans` housekeeping job found them, oldest first. Requires `instance.read`.

### Event stream

- [Stream change events](https://docs.marfa.so/api-reference/event-stream/streamEvents): Opens a Server-Sent Events stream of the changes to items and edges that you can read. Send `Last-Event-ID` to resume after a disconnect, or `copy=1` to follow a working copy.

### Webhooks

- [Create a webhook](https://docs.marfa.so/api-reference/webhooks/createWebhook): Creates a webhook that sends the events you name to `url`. It belongs to your key, or your app's grant: Marfa deletes it when that is revoked, and sends nothing while it lacks `webhooks.manage` or the key has expired.
- [Get a webhook](https://docs.marfa.so/api-reference/webhooks/getWebhook): Returns a webhook and its maker, with its secret redacted. The owner's browser session and local command can read any subscription; keys and apps can read only their own.
- [List webhooks](https://docs.marfa.so/api-reference/webhooks/listWebhooks): Returns webhooks and their makers, with secrets redacted. The owner's browser session and local command see every subscription; keys and apps see only their own.
- [Update a webhook](https://docs.marfa.so/api-reference/webhooks/updateWebhook): Updates a webhook and returns it. Fields you leave out keep their values. Marfa cancels a pending delivery if you change `url`, set `active` to `false`, or change `events` or `type_filter` to exclude it. To change the secret, create a new webhook.
- [Delete a webhook](https://docs.marfa.so/api-reference/webhooks/deleteWebhook): Deletes a webhook and cancels its pending deliveries.
- [List webhook deliveries](https://docs.marfa.so/api-reference/webhooks/listWebhookDeliveries): Returns delivery metadata without event payloads, newest first. The owner's browser session and local command can inspect any subscription; keys and apps can inspect only their own.
- [Redeliver a webhook delivery](https://docs.marfa.so/api-reference/webhooks/redeliverWebhookDelivery): Redelivers a failed delivery, queuing it again at the current URL. The owner's recently authenticated browser session or local command can retry any subscription; keys and apps can retry only their own.
- [Receive a webhook event](https://docs.marfa.so/api-reference/webhooks/receiveWebhookEvent): Marfa sends this request to a webhook's `url` for each event it subscribes to, with only what the webhook's credential can read when it's sent. A delivery can arrive more than once: use `delivery_id` to recognize a repeat.

### Folders

- [Create a folder](https://docs.marfa.so/api-reference/folders/createFolder): 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.
- [List folders](https://docs.marfa.so/api-reference/folders/listFolders): Returns active folder summaries, newest first, for the owner or a private local command. Revoked folders are excluded. Read reported copies with `GET /folders/{id}/status`.
- [Update a folder](https://docs.marfa.so/api-reference/folders/updateFolder): Updates a folder's title and settings at the version you read. Each setting you send replaces its value whole; omitted settings stay. Removes stored properties the folder type does not declare.
- [Revoke a folder](https://docs.marfa.so/api-reference/folders/revokeFolder): Revokes a folder: moves it to `revoked`, a terminal state, and sets `revoked_at`. The items placed in it keep their `in-folder` edges.
- [Report a folder status](https://docs.marfa.so/api-reference/folders/reportFolderStatus): Reports your sign-in's status for one folder copy, replacing its earlier report, and returns the latest accepted sequence and receipt time. An equal or older sequence leaves the stored report unchanged.
- [Get a folder status](https://docs.marfa.so/api-reference/folders/getFolderStatus): Returns the latest folder-copy reports grouped by sign-in, with receipt ages and totals from sign-ins that still stand. Historical reports remain visible.

### Views

- [Create a view](https://docs.marfa.so/api-reference/views/createView): Creates a view: a `system.view` item whose properties say which items it lists and how its layouts show them. The item endpoints can't write one.
- [Update a view](https://docs.marfa.so/api-reference/views/updateView): Updates a view's title, query or layouts. Each one you send replaces the current value whole, and those you leave out stay as they are. Send the `version` you read.
- [Delete a view](https://docs.marfa.so/api-reference/views/deleteView): Deletes an active or revoked view permanently, with no trash. Marfa announces it as `item.purged`, so every app drops it. The items it listed don't change.

### Connectors

- [Register a connector](https://docs.marfa.so/api-reference/connectors/registerConnector): Registers your key as a connector and returns it. Repeating registration updates its name and description and keeps its ID. A successor key inherits its own source's inbound endpoints and retained deliveries.
- [Get a connector](https://docs.marfa.so/api-reference/connectors/getConnector): Returns a connector, with when it last sent a heartbeat, its last run and any hold on it.
- [List connectors](https://docs.marfa.so/api-reference/connectors/listConnectors): Returns your registration, or every registration if you hold `connectors.manage`, newest first.
- [Delete a connector](https://docs.marfa.so/api-reference/connectors/deleteConnector): Deletes the connector, its runs and hold, and its inbound endpoints with every delivery they stored. Its state document and agreements stay with its source, for a later key with the same source.
- [Send a connector heartbeat](https://docs.marfa.so/api-reference/connectors/sendConnectorHeartbeat): Sends a heartbeat, which sets the connector's `last_heartbeat_at` to the current time, and returns that time. Marfa takes no action when heartbeats stop.
- [Report a connector run](https://docs.marfa.so/api-reference/connectors/reportConnectorRun): Reports one run of the connector, with its outcome and times, and returns it. Marfa keeps the last 100 runs and drops older ones.
- [List connector runs](https://docs.marfa.so/api-reference/connectors/listConnectorRuns): Returns the runs the connector reported, newest first.

### Connector state

- [Take a connector hold](https://docs.marfa.so/api-reference/connector-state/takeConnectorHold): Takes the connector's hold for `process`, or renews it if `process` already holds it. Only the process holding a live hold can replace the state document or write agreements.
- [Release a connector hold](https://docs.marfa.so/api-reference/connector-state/releaseConnectorHold): Releases the hold if `process` holds it, so another process can take it at once. Returns the same either way, and leaves another process's hold in place.
- [Get a connector's state](https://docs.marfa.so/api-reference/connector-state/getConnectorState): Returns the state document of the connector's source. A later key with the same source reads the same document.
- [Replace a connector's state](https://docs.marfa.so/api-reference/connector-state/replaceConnectorState): Replaces the whole state document of the connector's source. Only the process holding a live hold can write it.
- [Delete a connector's state](https://docs.marfa.so/api-reference/connector-state/deleteConnectorState): Deletes the state document, current problems and every agreement of the connector's source, which every registration of that source reads. No hold is needed.
- [Write connector agreements](https://docs.marfa.so/api-reference/connector-state/writeConnectorAgreements): Writes and clears the connector's agreements, its records of what it and its vendor last agreed about each item. Only the process holding a live hold can write them.
- [List connector agreements](https://docs.marfa.so/api-reference/connector-state/listConnectorAgreements): Returns the agreements of the connector's source, the one written longest ago first. Items whose type you can't read are left out, so a page can be short with more to follow.
- [Look up connector agreements](https://docs.marfa.so/api-reference/connector-state/lookupConnectorAgreements): Looks up the agreements of the named items and returns those that exist, each item once, in the order you first named it. An item whose type you can't read is left out.

### Inbound webhooks

- [Create an inbound endpoint](https://docs.marfa.so/api-reference/inbound-webhooks/createInboundEndpoint): Creates an inbound endpoint for the connector and returns it. Save its `path`: this is the only response that shows it in full.
- [List inbound endpoints](https://docs.marfa.so/api-reference/inbound-webhooks/listInboundEndpoints): Returns the connector's inbound endpoints, newest first, retired ones included.
- [Retire an inbound endpoint](https://docs.marfa.so/api-reference/inbound-webhooks/retireInboundEndpoint): Retires an inbound endpoint, so its address stops accepting deliveries. It stays listed with `retired_at`, and deliveries it already stored stay readable until they age out.
- [List inbound deliveries](https://docs.marfa.so/api-reference/inbound-webhooks/listInboundDeliveries): Returns the webhook deliveries the connector received, oldest first, without their bodies. Only those not yet handled, unless you set `state`.
- [Get an inbound delivery's body](https://docs.marfa.so/api-reference/inbound-webhooks/getInboundDeliveryBody): Returns a delivery's body exactly as it arrived, as `application/octet-stream` whatever the sender declared.
- [Mark inbound deliveries handled](https://docs.marfa.so/api-reference/inbound-webhooks/markInboundDeliveriesHandled): Marks each named delivery handled, with an outcome, and returns them in the order you named. The first mark stands: marking a delivery again returns it unchanged.

### API keys

- [Create an API key](https://docs.marfa.so/api-reference/api-keys/createKey): Creates an API key and returns it with its plaintext `key`, shown only here. If the body names none of `permissions`, the five permission maps and `sources`, the key gets everything you hold; if it names any, the key holds only what it names.
- [Get the current API key](https://docs.marfa.so/api-reference/api-keys/getCurrentKey): Returns the API key that sends the request, without its plaintext. Any key can read itself, whatever it holds, so a process can check what it was given.
- [List API keys](https://docs.marfa.so/api-reference/api-keys/listKeys): Returns key metadata without plaintext. `keys.manage` and direct owner or local authority list all keys; `keys.mint` lists keys within the caller's current reach. Requires `keys.mint`, `keys.manage`, or direct owner or local authority.
- [Update an API key](https://docs.marfa.so/api-reference/api-keys/updateKey): Updates a key and returns it. Each supplied field replaces its value; omitted fields stay unchanged. Requires `keys.mint`, `keys.manage`, or direct owner or local authority.
- [Revoke an API key](https://docs.marfa.so/api-reference/api-keys/revokeKey): Revokes a key, ending its event streams and queued bulk actions. `keys.manage` or direct owner or local authority can revoke any key. A caller with only `keys.mint` can revoke keys within its current reach.

### Apps

- [Register an OAuth client](https://docs.marfa.so/api-reference/apps/registerOAuthClient): Registers an OAuth client for an app and returns it with its `client_id`. Send no credential; a web page can call it from a browser on any origin. The `client_credentials` grant isn't available: a program that acts for no person uses an API key.
- [List app grants](https://docs.marfa.so/api-reference/apps/listAppGrants): Returns every active app grant in one page. Requires `grants.manage` or direct authority.
- [Narrow an app grant](https://docs.marfa.so/api-reference/apps/narrowAppGrant): Narrows standing access. Requires a recent owner sign-in or private authority. Overbroad tokens, their refresh chains and pending codes end; covered chains keep working. The app may need to reconnect. Minted keys keep working.
- [Revoke an app grant](https://docs.marfa.so/api-reference/apps/revokeAppGrant): Revokes the app's tokens and consent. Requires `grants.manage` or direct authority; an owner browser needs a sign-in within five minutes.

### Owner

- [Claim the instance](https://docs.marfa.so/api-reference/owner/createOwner): Creates the one owner using a machine-issued setup code or setup-only browser session. A claimed instance never reopens setup. A claim from the instance's own origin, which the setup page sends, also signs the owner in with a session cookie.
- [Get the owner](https://docs.marfa.so/api-reference/owner/getOwner): Returns the owner of the claimed instance. Requires a direct owner sign-in or local process authority.
- [Update the owner](https://docs.marfa.so/api-reference/owner/updateOwner): Updates the owner's email or name, or removes the picture. Requires a direct owner sign-in within five minutes or private machine authority. Changing email needs no confirmation; credentials, sessions, and grants keep their identity.
- [Update the owner's profile](https://docs.marfa.so/api-reference/owner/updateProfile): Updates the owner's name or removes the picture and returns `ok: true`. Requires profile write permission for every submitted field; email cannot be changed here. All fields commit together.
- [Replace the owner's picture](https://docs.marfa.so/api-reference/owner/replaceOwnerPicture): Stores the request body as the owner's picture and returns the owner. Requires a direct owner sign-in within five minutes or private machine authority.
- [Replace the picture as an app](https://docs.marfa.so/api-reference/owner/replaceProfilePicture): Stores the request body as the owner's picture and returns `ok: true`. Requires profile write permission for the avatar.
- [Get the owner's picture](https://docs.marfa.so/api-reference/owner/getOwnerPicture): Returns the owner's picture as an image download. Requires an owner sign-in or a credential with profile read permission for the avatar. Send `If-None-Match` to revalidate.

### Sign-ins and passkeys

- [List sign-ins](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/listSignIns): Returns every browser, app and key that can reach Marfa, marking the browser that sent the request. Requires the owner's browser session or the local command.
- [Rename a sign-in](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/renameSignIn): Renames an app or a key and returns the sign-in. A key's name is its `label`. Requires the owner's browser session, signed in within the last five minutes, or the local command.
- [End a sign-in](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/endSignIn): Ends a sign-in at once: it can't refresh or make another request. An app's keys stay unless `revoke_keys` is `true`. Needs the owner's browser session or the local command. A browser over five minutes old can end only itself, without `revoke_keys`.
- [List passkeys](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/listOwnerPasskeys): Returns every registered owner passkey, oldest first. Requires the owner's browser session or private local authority.
- [Rename a passkey](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/renameOwnerPasskey): Renames the passkey and returns its public details. Requires the owner's browser session authenticated within five minutes or private local authority.
- [Delete a passkey](https://docs.marfa.so/api-reference/sign-ins-and-passkeys/deleteOwnerPasskey): Deletes one passkey so it cannot sign in again. Existing sign-ins remain usable. Requires the owner's browser session authenticated within five minutes or private local authority.

### Instance

- [Get the instance](https://docs.marfa.so/api-reference/instance/getInstance): Returns a description of the instance: its display name, `instance_id`, the build it runs, the release it was made as when it is one, the contract version it speaks and the features it serves. Needs no credential.
- [Get the configuration](https://docs.marfa.so/api-reference/instance/getConfig): Returns the instance configuration: its display name, enforcement levers and live settings, with its `instance_id`. A setting nobody has set is left out. Requires `config.manage`.
- [Update the configuration](https://docs.marfa.so/api-reference/instance/updateConfig): Changes only the settings the body names and returns the whole configuration. A setting you leave out stays as it is, and `null` removes one so its default applies. `enforcement` is one setting: send every lever you want on. Requires `config.manage`.
- [Replace the configuration](https://docs.marfa.so/api-reference/instance/replaceConfig): Replaces the instance configuration with the body and returns it. A setting you leave out goes back to its default, so send the whole configuration with your change. To change only some settings, use `PATCH`. Requires `config.manage`.

### Health and maintenance

- [List attention items](https://docs.marfa.so/api-reference/health-and-maintenance/listAttention): Returns current concerns for the owner or a private local command. Failed or timed-out checks appear as unavailable items alongside known concerns. An empty list means every check completed without a concern.
- [Get instance metrics](https://docs.marfa.so/api-reference/health-and-maintenance/getInstanceMetrics): Returns instance-wide counters and process uptime. Requires `instance.read`; the counters include records outside your content permissions.
- [List audit log entries](https://docs.marfa.so/api-reference/health-and-maintenance/listAuditLog): Returns audit log entries, newest first. Marfa records changes, sign-ins and exports here, not other reads. Requires `audit.read`.
- [List housekeeping jobs](https://docs.marfa.so/api-reference/health-and-maintenance/listHousekeeping): Returns every housekeeping job Marfa runs: its interval, when it's next due, whether a run holds it, and what its last run did. A job a server setting switches off isn't listed. Requires `instance.read`.
- [Run a housekeeping job](https://docs.marfa.so/api-reference/health-and-maintenance/runHousekeeping): Runs a housekeeping job now, waits for it to finish, and returns what the run did. A failed run still returns `200`, with the failure in `outcome` and `error`. Requires `instance.maintain`.
- [List retired platform types](https://docs.marfa.so/api-reference/health-and-maintenance/listRetiredPlatformTypes): Returns the platform types that this instance still carries but this build no longer ships, with how many items use each. They stay in `GET /types` until removed. Requires `instance.read`.
- [Delete a retired platform type](https://docs.marfa.so/api-reference/health-and-maintenance/deleteRetiredPlatformType): Deletes one retired platform type: a type this build no longer ships. The type stops resolving at once. Requires `instance.maintain`.

### Export and restore

- [Export an archive](https://docs.marfa.so/api-reference/export-and-restore/exportArchive): Exports an archive of the items, metadata and edges you can read, excluding trash unless requested. The owner can use their browser session. An archive can be read by `POST /restore`.
- [Restore from an archive](https://docs.marfa.so/api-reference/export-and-restore/restoreArchive): Restores an exported archive atomically and returns counts of written and skipped records. Other writes wait until it finishes. Requires local authority or the owner, authenticated within five minutes before the request starts.

### Resources

- [Changelog](https://docs.marfa.so/changelog.md): What each release of Marfa changed for someone running an instance or building on it.
- [The contract](https://github.com/withmarfa/marfa/tree/main/conformance/spec)