# API reference (/reference/api)

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 [#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.

**Data** (73 operations)

- **Items** (20 operations): The records Marfa stores, each of a type, and the ways to read and change them.
  - `POST /items`: [Create an item](/reference/api/items/createItem)
  - `GET /items/{id}`: [Get an item](/reference/api/items/getItem)
  - `GET /items`: [List items](/reference/api/items/listItems)
  - `PATCH /items/{id}`: [Update an item](/reference/api/items/updateItem)
  - `DELETE /items/{id}`: [Trash an item](/reference/api/items/deleteItem)
  - `POST /items/trash-preview`: [Preview trashing items](/reference/api/items/previewItemTrash)
  - `POST /items/trash`: [Trash items](/reference/api/items/trashItems)
  - `POST /items/{id}/restore`: [Restore an item](/reference/api/items/restoreItem)
  - `POST /items/{id}/purge`: [Purge an item](/reference/api/items/purgeItem)
  - `POST /items/{id}/transition`: [Change an item's state](/reference/api/items/transitionItem)
  - `GET /items/{id}/versions`: [List item versions](/reference/api/items/listItemVersions)
  - `POST /items/lookup`: [Look up items](/reference/api/items/lookupItems)
  - `POST /items/titles`: [Find items by title](/reference/api/items/findItemsByTitle)
  - `POST /items/bulk-get`: [Get items in bulk](/reference/api/items/bulkGetItems)
  - `POST /items/counts`: [Count linked items and rows](/reference/api/items/countItemLinks)
  - `POST /items/bulk`: [Upsert items in bulk](/reference/api/items/bulkUpsertItems)
  - `GET /items/stats`: [Get item counts](/reference/api/items/getItemStats)
  - `GET /items/summaries`: [List item summaries](/reference/api/items/listItemSummaries)
  - `GET /occurrences`: [List event occurrences](/reference/api/items/listOccurrences)
  - `POST /items/tombstones`: [Settle tombstones](/reference/api/items/settleTombstones)
- **Trash** (2 operations): Items in the trash: list them, move an item in, and restore, purge or empty them.
  - `GET /trash`: [List the trash](/reference/api/trash/listTrash)
  - `POST /trash/empty`: [Empty the trash](/reference/api/trash/emptyTrash)
- **Bulk actions** (3 operations): One change applied to every item a filter matches, run as a job you can follow and cancel.
  - `POST /items/bulk-actions`: [Apply a bulk action](/reference/api/bulk-actions/applyBulkAction)
  - `GET /items/bulk-actions/jobs/{id}`: [Get a bulk-action job](/reference/api/bulk-actions/getBulkActionJob)
  - `POST /items/bulk-actions/jobs/{id}/cancel`: [Cancel a bulk-action job](/reference/api/bulk-actions/cancelBulkActionJob)
- **Metadata** (4 operations): An item's tags and extensions together, and the tags in use.
  - `PUT /items/{id}/tags`: [Replace an item's tags](/reference/api/metadata/replaceItemTags)
  - `POST /items/{id}/tags`: [Add tags to an item](/reference/api/metadata/addItemTags)
  - `DELETE /items/{id}/tags/{tag}`: [Remove a tag from an item](/reference/api/metadata/removeItemTag)
  - `GET /tags`: [List tags](/reference/api/metadata/listTags)
- **Extensions** (4 operations): JSON objects attached to an item, one per namespace.
  - `GET /items/{id}/extensions/{namespace}`: [Get an extension namespace](/reference/api/extensions/getItemExtension)
  - `GET /items/{id}/extensions`: [List extension namespaces](/reference/api/extensions/listItemExtensions)
  - `PUT /items/{id}/extensions/{namespace}`: [Replace an extension namespace](/reference/api/extensions/replaceItemExtension)
  - `DELETE /items/{id}/extensions/{namespace}`: [Delete an extension namespace](/reference/api/extensions/deleteItemExtension)
- **Tables** (7 operations): The rows an item holds in the tables its type declares.
  - `POST /items/{id}/tables/{table}/rows`: [Write table rows](/reference/api/tables/writeTableRows)
  - `GET /items/{id}/tables/{table}/rows/{row}`: [Get a table row](/reference/api/tables/getTableRow)
  - `GET /items/{id}/tables/{table}/rows`: [List table rows](/reference/api/tables/listTableRows)
  - `GET /items/{id}/tables`: [List an item's tables](/reference/api/tables/listItemTables)
  - `GET /items/{id}/tables/{table}/totals`: [Get table totals](/reference/api/tables/getTableTotals)
  - `GET /items/{id}/tables/{table}/batches`: [List table batches](/reference/api/tables/listTableBatches)
  - `POST /items/{id}/tables/{table}/batches/{batch}/undo`: [Undo a table batch](/reference/api/tables/undoTableBatch)
- **Edges** (8 operations): Typed, directed relationships between items.
  - `POST /edges`: [Create an edge](/reference/api/edges/createEdge)
  - `GET /edges/{id}`: [Get an edge](/reference/api/edges/getEdge)
  - `GET /edges`: [List edges](/reference/api/edges/listEdges)
  - `PATCH /edges/{id}`: [Update an edge](/reference/api/edges/updateEdge)
  - `DELETE /edges/{id}`: [Delete an edge](/reference/api/edges/deleteEdge)
  - `POST /edges/bulk`: [Upsert edges in bulk](/reference/api/edges/bulkUpsertEdges)
  - `GET /items/{id}/edges`: [List outbound edges](/reference/api/edges/listItemEdges)
  - `GET /items/{id}/backrefs`: [List inbound edges](/reference/api/edges/listItemBackrefs)
- **Search** (1 operation): Full-text search across items.
  - `GET /search`: [Search items](/reference/api/search/searchItems)
- **Types** (9 operations): The types items can have: those Marfa ships and those registered on this instance.
  - `POST /types`: [Register a type](/reference/api/types/registerType)
  - `GET /types/{id}`: [Get a type](/reference/api/types/getType)
  - `GET /types`: [List types](/reference/api/types/listTypes)
  - `PUT /types/{id}`: [Replace a type](/reference/api/types/replaceType)
  - `DELETE /types/{id}`: [Delete a type](/reference/api/types/deleteType)
  - `POST /types/{id}/move`: [Move items to another type](/reference/api/types/moveType)
  - `POST /types/normalize`: [Normalize a type definition](/reference/api/types/normalizeType)
  - `PUT /types/{id}/icon`: [Set a type's icon](/reference/api/types/setTypeIcon)
  - `DELETE /types/{id}/icon`: [Clear a type's icon](/reference/api/types/clearTypeIcon)
- **Edge types** (3 operations): The types edges can have, each with its cardinality and cascade rule.
  - `POST /edge-types`: [Register an edge type](/reference/api/edge-types/registerEdgeType)
  - `GET /edge-types`: [List edge types](/reference/api/edge-types/listEdgeTypes)
  - `DELETE /edge-types/{id}`: [Delete an edge type](/reference/api/edge-types/deleteEdgeType)
- **Blobs** (8 operations): Bytes stored by content hash, and the stores that hold them.
  - `POST /blobs`: [Upload a blob](/reference/api/blobs/uploadBlob)
  - `GET /blobs/{hash}`: [Download a blob](/reference/api/blobs/downloadBlob)
  - `HEAD /blobs/{hash}`: [Check a blob](/reference/api/blobs/checkBlob)
  - `GET /blobs/{hash}/url`: [Get a blob URL](/reference/api/blobs/getBlobUrl)
  - `GET /blobs/{hash}/copies`: [List a blob's copies](/reference/api/blobs/listBlobCopies)
  - `DELETE /blobs/{hash}/copies/{store}`: [Delete one copy of a blob](/reference/api/blobs/deleteBlobCopy)
  - `GET /blobs/stores`: [List blob stores](/reference/api/blobs/listBlobStores)
  - `GET /blobs/orphans`: [List orphaned blobs](/reference/api/blobs/listBlobOrphans)
- **Views** (4 operations): Saved lists of items with their sort and grouping, held as `system.view` items.
  - `POST /views`: [Create a view](/reference/api/views/createView)
  - `GET /views/{id}/items`: [List a view's items](/reference/api/views/listViewItems)
  - `PATCH /views/{id}`: [Update a view](/reference/api/views/updateView)
  - `DELETE /views/{id}`: [Delete a view](/reference/api/views/deleteView)

**Changes** (9 operations)

- **Event stream** (1 operation): Changes to items, table rows and edges, streamed as they happen.
  - `GET /events`: [Stream change events](/reference/api/event-stream/streamEvents)
- **Webhooks** (8 operations): 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.
  - `POST /webhooks`: [Create a webhook](/reference/api/webhooks/createWebhook)
  - `GET /webhooks/{id}`: [Get a webhook](/reference/api/webhooks/getWebhook)
  - `GET /webhooks`: [List webhooks](/reference/api/webhooks/listWebhooks)
  - `PATCH /webhooks/{id}`: [Update a webhook](/reference/api/webhooks/updateWebhook)
  - `DELETE /webhooks/{id}`: [Delete a webhook](/reference/api/webhooks/deleteWebhook)
  - `GET /webhooks/{id}/deliveries`: [List webhook deliveries](/reference/api/webhooks/listWebhookDeliveries)
  - `POST /webhooks/{id}/deliveries/{delivery_id}/redeliver`: [Redeliver a webhook delivery](/reference/api/webhooks/redeliverWebhookDelivery)
  - `WEBHOOK event`: [Receive a webhook event](/reference/api/webhooks/receiveWebhookEvent)

**Access** (26 operations)

- **API keys** (5 operations): The keys that authenticate requests to this instance, and the permissions each holds.
  - `POST /keys`: [Create an API key](/reference/api/api-keys/createKey)
  - `GET /keys/current`: [Get the current API key](/reference/api/api-keys/getCurrentKey)
  - `GET /keys`: [List API keys](/reference/api/api-keys/listKeys)
  - `PATCH /keys/{id}`: [Update an API key](/reference/api/api-keys/updateKey)
  - `DELETE /keys/{id}`: [Revoke an API key](/reference/api/api-keys/revokeKey)
- **Apps** (8 operations): Apps that register as OAuth clients, how they sign in, and the access the owner grants them.
  - `POST /oauth/register`: [Register an app](/reference/api/apps/registerOAuthClient)
  - `GET /grants`: [List app grants](/reference/api/apps/listAppGrants)
  - `PATCH /grants/{id}`: [Narrow an app grant](/reference/api/apps/narrowAppGrant)
  - `DELETE /grants/{id}`: [Revoke an app grant](/reference/api/apps/revokeAppGrant)
  - `GET /oauth/authorize`: [Authorize an app](/reference/api/apps/authorizeApp)
  - `POST /oauth/device-authorization`: [Request a device code](/reference/api/apps/requestDeviceCode)
  - `POST /oauth/token`: [Exchange a code for a token](/reference/api/apps/exchangeToken)
  - `POST /oauth/revoke`: [Revoke a token](/reference/api/apps/revokeToken)
- **Owner** (5 operations): The instance's owner and their profile.
  - `POST /owner`: [Claim the instance](/reference/api/owner/createOwner)
  - `GET /profile`: [Get the owner's profile](/reference/api/owner/getProfile)
  - `PATCH /profile`: [Update the owner's profile](/reference/api/owner/updateProfile)
  - `GET /profile/avatar`: [Get the profile avatar](/reference/api/owner/getProfileAvatar)
  - `PUT /profile/avatar`: [Replace the avatar as an app](/reference/api/owner/replaceProfileAvatar)
- **Sign-ins and passkeys** (8 operations): The browsers, apps and keys that can reach the instance, and the owner's passkeys and password.
  - `GET /owner/sign-ins`: [List sign-ins](/reference/api/sign-ins-and-passkeys/listSignIns)
  - `PATCH /owner/sign-ins/{id}`: [Rename a sign-in](/reference/api/sign-ins-and-passkeys/renameSignIn)
  - `PUT /owner/password`: [Replace the password](/reference/api/sign-ins-and-passkeys/replaceOwnerPassword)
  - `DELETE /owner/sign-ins/{id}`: [End a sign-in](/reference/api/sign-ins-and-passkeys/endSignIn)
  - `GET /owner/passkeys`: [List passkeys](/reference/api/sign-ins-and-passkeys/listOwnerPasskeys)
  - `PATCH /owner/passkeys/{id}`: [Rename a passkey](/reference/api/sign-ins-and-passkeys/renameOwnerPasskey)
  - `DELETE /owner/passkeys/{id}`: [Delete a passkey](/reference/api/sign-ins-and-passkeys/deleteOwnerPasskey)
  - `GET /owner/passkeys/add-url`: [Get the passkey add link](/reference/api/sign-ins-and-passkeys/getPasskeyAddUrl)

**Connectors** (24 operations)

- **Connectors** (7 operations): Processes outside the server that read and write on your behalf, with their heartbeats and runs.
  - `POST /connectors`: [Register a connector](/reference/api/connectors/registerConnector)
  - `GET /connectors/{id}`: [Get a connector](/reference/api/connectors/getConnector)
  - `GET /connectors`: [List connectors](/reference/api/connectors/listConnectors)
  - `DELETE /connectors/{id}`: [Delete a connector](/reference/api/connectors/deleteConnector)
  - `POST /connectors/{id}/heartbeat`: [Send a connector heartbeat](/reference/api/connectors/sendConnectorHeartbeat)
  - `POST /connectors/{id}/runs`: [Report a connector run](/reference/api/connectors/reportConnectorRun)
  - `GET /connectors/{id}/runs`: [List connector runs](/reference/api/connectors/listConnectorRuns)
- **Connector state** (8 operations): What the instance keeps for a connector's source: its hold, its state document and its agreements.
  - `POST /connectors/{id}/hold`: [Take a connector hold](/reference/api/connector-state/takeConnectorHold)
  - `DELETE /connectors/{id}/hold`: [Release a connector hold](/reference/api/connector-state/releaseConnectorHold)
  - `GET /connectors/{id}/state`: [Get a connector's state](/reference/api/connector-state/getConnectorState)
  - `PUT /connectors/{id}/state`: [Replace a connector's state](/reference/api/connector-state/replaceConnectorState)
  - `DELETE /connectors/{id}/state`: [Delete a connector's state](/reference/api/connector-state/deleteConnectorState)
  - `POST /connectors/{id}/agreements`: [Write connector agreements](/reference/api/connector-state/writeConnectorAgreements)
  - `GET /connectors/{id}/agreements`: [List connector agreements](/reference/api/connector-state/listConnectorAgreements)
  - `POST /connectors/{id}/agreements/lookup`: [Look up connector agreements](/reference/api/connector-state/lookupConnectorAgreements)
- **Inbound webhooks** (6 operations): Addresses where a service sends requests to a connector, and the deliveries Marfa stores for it.
  - `POST /connectors/{id}/endpoints`: [Create an inbound endpoint](/reference/api/inbound-webhooks/createInboundEndpoint)
  - `GET /connectors/{id}/endpoints`: [List inbound endpoints](/reference/api/inbound-webhooks/listInboundEndpoints)
  - `DELETE /connectors/{id}/endpoints/{endpoint_id}`: [Retire an inbound endpoint](/reference/api/inbound-webhooks/retireInboundEndpoint)
  - `GET /connectors/{id}/deliveries`: [List inbound deliveries](/reference/api/inbound-webhooks/listInboundDeliveries)
  - `GET /connectors/{id}/deliveries/{delivery_id}/body`: [Get an inbound delivery's body](/reference/api/inbound-webhooks/getInboundDeliveryBody)
  - `POST /connectors/{id}/deliveries/handled`: [Mark inbound deliveries handled](/reference/api/inbound-webhooks/markInboundDeliveriesHandled)
- **Sources** (3 operations): The codes items carry to say what wrote them, and the name and mark each is shown by.
  - `GET /sources`: [List sources](/reference/api/sources/listSources)
  - `GET /sources/{source}`: [Get a source](/reference/api/sources/getSource)
  - `PATCH /sources/{source}`: [Name a source](/reference/api/sources/updateSource)

**Instance** (28 operations)

- **Instance** (7 operations): The instance itself: what it is and how it's configured.
  - `GET /`: [Get the instance](/reference/api/instance/getInstance)
  - `GET /overview`: [Get an overview](/reference/api/instance/getOverview)
  - `GET /config`: [Get the configuration](/reference/api/instance/getConfig)
  - `GET /config/settings`: [List the settings](/reference/api/instance/listSettings)
  - `POST /config/address-check`: [Check an address change](/reference/api/instance/checkAddressChange)
  - `PATCH /config`: [Update the configuration](/reference/api/instance/updateConfig)
  - `PUT /config`: [Replace the configuration](/reference/api/instance/replaceConfig)
- **Health and maintenance** (9 operations): How the instance is doing: its health, what needs attention, its metrics, its audit log, its housekeeping jobs and its updates.
  - `GET /health`: [Get the instance's health](/reference/api/health-and-maintenance/getHealth)
  - `GET /attention`: [List attention items](/reference/api/health-and-maintenance/listAttention)
  - `GET /metrics`: [Get instance metrics](/reference/api/health-and-maintenance/getInstanceMetrics)
  - `GET /audit`: [List audit log entries](/reference/api/health-and-maintenance/listAuditLog)
  - `GET /housekeeping`: [List housekeeping jobs](/reference/api/health-and-maintenance/listHousekeeping)
  - `POST /housekeeping/{name}/run`: [Run a housekeeping job](/reference/api/health-and-maintenance/runHousekeeping)
  - `POST /clock/confirm`: [Confirm the clock](/reference/api/health-and-maintenance/confirmClock)
  - `GET /update`: [Get the update status](/reference/api/health-and-maintenance/getUpdate)
  - `POST /update`: [Start an update](/reference/api/health-and-maintenance/startUpdate)
- **Export and restore** (6 operations): Export the instance's data, and restore it from an archive.
  - `GET /export`: [Export an archive](/reference/api/export-and-restore/exportArchive)
  - `POST /restore`: [Restore from an archive](/reference/api/export-and-restore/restoreArchive)
  - `GET /backups`: [List backups](/reference/api/export-and-restore/listBackups)
  - `POST /backups`: [Take a backup](/reference/api/export-and-restore/runBackup)
  - `POST /backups/folder/adopt`: [Adopt a backup folder](/reference/api/export-and-restore/adoptBackupFolder)
  - `POST /backups/{instance_id}/{name}/restore`: [Restore a backup](/reference/api/export-and-restore/restoreBackup)
- **Folders** (6 operations): A folder's settings, held as a `system.folder` item.
  - `POST /folders`: [Create a folder](/reference/api/folders/createFolder)
  - `GET /folders`: [List folders](/reference/api/folders/listFolders)
  - `PATCH /folders/{id}`: [Update a folder](/reference/api/folders/updateFolder)
  - `POST /folders/{id}/revoke`: [Revoke a folder](/reference/api/folders/revokeFolder)
  - `PUT /folders/{id}/status`: [Report a folder status](/reference/api/folders/reportFolderStatus)
  - `GET /folders/{id}/status`: [Get a folder status](/reference/api/folders/getFolderStatus)

## Send a request [#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](/build/access) explains both, and [Manage keys](/run/manage-keys) shows how to make a key.

A request body is JSON, sent with `Content-Type: application/json`, except [Upload a blob](/reference/api/blobs/uploadBlob), which takes a file's bytes. This request makes a file item from a picture already uploaded:

```http title="Request"
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:

Response (201 Created):

```json
{
  "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](/reference/errors) explains.

## Rules every operation follows [#rules-every-operation-follows]

Marfa stores typed records, called items, and the edges between them. This reference describes its HTTP API.

### Authentication [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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]

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.
