Items

Update an item

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. A no-change update writes nothing. To change its type, send type with retype: true.

PATCH
/items/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path parameters

id*string

The ID of the item.

Query parameters

conflict?"auto"

Who resolves a version conflict. auto has Marfa resolve it by the type's merge policy. Leave it out and Marfa returns the conflict for you to resolve.

Value in"auto"

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
properties?

The properties to write. They lay over the item's properties, or become all of them when properties_mode is replace. As in POST /items, strict mode refuses an undeclared property, and a whole number whose digits a 64-bit float doesn't keep is refused.

clear_properties?array<>

Properties to remove from the item. Every other property stays as it is. Naming one the item doesn't have isn't an error. A name can't also be in properties.

type?string

The item's type. It must match the item's current type unless retype is true.

properties_mode?string

How properties applies. merge (the default) lays them over the item's properties. replace takes them as the whole set, so a property you leave out is cleared.

Value in"merge""replace"
retype?boolean

true moves the item to type. You need write on both types, and the properties the item ends up with must fit the new type. Naming the item's current type changes nothing.

version*integer

The version of the item you read, which this update is based on.

Range0 <= value
version_match?"exact"

exact requires the item to still hold version, even if the fields changed do not collide. If omitted, a stale write can merge over changes to other fields.

Value in"exact"
tier?string

Moves the item between library and feed.

Value in"library""feed"
occurred_at?string

When the item occurred, as an ISO 8601 time.

source_id?string

The item's new source_id. Marfa moves its natural key under the item's own source, which never changes.

edges?

Edge types to replace, each mapped to the item IDs it should now point to. An edge to an ID you still list stays as it is, with its properties. An empty list removes every edge of that type. Types you don't name are untouched. A new edge made this way carries no properties, so an edge type that requires one refuses the write.

Response body

About errors

Returns the updated item and its metadata, with acknowledged: true if the update changed nothing. If conflict=auto resolved a collision, conflict_resolution lists the fields and strategies. A keep_both_copies field keeps the current value and puts yours on a new sibling tagged conflicted-copy, with a derived-from edge to this item.

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.

conflict_resolution?

What Marfa did to resolve a conflict. Present only when conflict=auto resolved one. conflicted_copy_id is the ID of the sibling item that holds the losing values, which has a derived-from edge to this item.

  • missing_required_field: version is missing.
  • validation_error: the body is malformed or changes nothing.
  • invalid_id: an ID isn't valid.
  • invalid_properties: the properties don't fit the type, or an inline edge lacks a property its type requires.
  • unknown_type: type isn't registered.
  • edge_constraint_violation, edge_cycle: an edge breaks its type's rules.
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 can read the item's type but don't have write on it (or on the type retype enters), or your credential reaches no type.
  • edge_type_not_permitted: you don't have write on an edge type in edges.
  • forbidden: you changed source_id on an item whose source your key doesn't write under or claim. details.source names it.
application/json
  1. response

An error response.

error*

What went wrong.

  • item_not_found: no item you can read has this ID or an ID an edge points to. For a trashed item, details.trashed is true if you can read its type.
  • edge_type_not_found: an edge names an edge type that doesn't exist.
  • edge_not_found: a repeat under the Idempotency-Key would show an edge you can't read now.
  • blob_not_found: blob_ref names bytes you didn't upload and can't read.
application/json
  1. response

An error response.

error*

What went wrong.

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

application/json
  1. response

An error response.

error*

What went wrong.

  • version_conflict: a stale or colliding write. current is the item now.
  • ancestor_unavailable: no readable snapshot of version.
  • source_id_conflict: another item under the source holds source_id.
  • link_taken: another item of the type holds the link.
  • type_mismatch: type differs without retype: true.
  • type_move_blocked: rows hold a table the new type lacks.
application/json
  1. response

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

error*

What went wrong.

current*

The item as it stands now.

ancestor*

The item at the version you sent.

conflicting_fields*array<string>

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

merge_policy*

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

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

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

application/json
  1. response

An error response.

error*

What went wrong.

  • idempotency_contract_changed: the first response was made under another contract version, so Marfa can't replay it. The write isn't repeated.
  • idempotency_key_reused: the key was first used for a different request. Nothing is written.
  • idempotency_result_not_retained: the first response was too large to keep, so Marfa can't replay it. The write isn't repeated.
application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

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

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X PATCH 'http://localhost:8600/items/string' \  -H 'Content-Type: application/json' \  -d '{  "version": 0}'
About errors
{  "item": {    "id": "01a1011a-4902-76cf-a4a9-88e99c038c8d",    "type": "acme.deal",    "state": "active",    "tier": "library",    "created_at": "2026-10-03T09:37:25.975Z",    "updated_at": "2026-10-03T09:39:50.097Z",    "last_activity_at": "2026-10-03T09:39:50.097Z",    "occurred_at": "2026-10-03T09:37:25.975Z",    "source": "crm",    "source_id": "deal-1042",    "version": 2,    "schema_version": 1,    "trashed_at": null,    "read_only": false,    "properties": {      "name": "Renewal for Example Co",      "amount": 12000,      "stage": "won"    },    "edges": {}  },  "metadata": {    "item_id": "01a1011a-4902-76cf-a4a9-88e99c038c8d",    "tags": [      "renewal"    ],    "extensions": {}  }}