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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
id*stringThe ID of the item.
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.
"auto"Idempotency-Key?stringA 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.
length <= 255X-Marfa-Instance-Id?stringThe 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.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- 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?stringThe item's type. It must match the item's current type unless retype is true.
properties_mode?stringHow 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.
"merge""replace"retype?booleantrue 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*integerThe version of the item you read, which this update is based on.
0 <= valueversion_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.
"exact"tier?stringMoves the item between library and feed.
"library""feed"occurred_at?stringWhen the item occurred, as an ISO 8601 time.
source_id?stringThe 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.
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- response
An item with its metadata.
item*The item.
metadata*The item's metadata.
acknowledged?booleantrue 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:versionis 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:typeisn't registered.edge_constraint_violation,edge_cycle: an edge breaks its type's rules.
application/json- 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- 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 typeretypeenters), or your credential reaches no type.edge_type_not_permitted: you don't have write on an edge type inedges.forbidden: you changedsource_idon an item whose source your key doesn't write under or claim.details.sourcenames it.
application/json- 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.trashedistrueif 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 theIdempotency-Keywould show an edge you can't read now.blob_not_found:blob_refnames bytes you didn't upload and can't read.
application/json- 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- response
An error response.
error*What went wrong.
version_conflict: a stale or colliding write.currentis the item now.ancestor_unavailable: no readable snapshot ofversion.source_id_conflict: another item under the source holdssource_id.link_taken: another item of the type holds the link.type_mismatch:typediffers withoutretype: true.type_move_blocked: rows hold a table the new type lacks.
application/json- 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- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X PATCH 'http://localhost:8600/items/string' \ -H 'Content-Type: application/json' \ -d '{ "version": 0}'{ "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": {} }}