Create an item
Creates an item. If source_id matches an existing item under the same source, updates that item instead. A repeated id, or an update that leaves the item as it is, returns the stored item with acknowledged: true and writes nothing.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
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
type*stringThe item's type identifier, such as core.note.
properties?The item's properties, checked against the type's schema. Strict mode refuses an undeclared property as invalid_properties (details.code unknown_property). A whole number whose digits a 64-bit float doesn't keep is refused: send it as a string.
id?stringA UUIDv7 you choose for the item. Leave it out and Marfa creates one. Sending an ID you already created returns the stored item, marked acknowledged.
state?stringThe item's first lifecycle state, one the type's lifecycle can reach. Defaults to active.
occurred_at?stringWhen the item occurred, as an ISO 8601 time. Defaults to the creation time.
source?stringThe source to key and stamp the item with. Defaults to your credential's own; it can also name one of your key's sources. An item's source never changes.
source_id?stringThe item's identifier at its source, such as a vendor's record ID. With source, it is the item's natural key: creating with a key that exists updates that item.
mode?stringupsert (the default) updates the item source_id matches. create_only writes nothing when an item already holds the source_id under the source, or the id, in any state, and answers item_exists (409) with details.existing_id.
"upsert""create_only"version?integerThe version you read. Used only when source_id matches a live item: the update then applies only if the item is still at this version. Ignored otherwise.
0 <= valuetier?stringThe item's tier. Defaults to your key's default_tier, else library. If source_id matches an existing item, leaving it out keeps that item's tier.
"library""feed"capture_latitude?numberThe latitude where the item was captured.
capture_longitude?numberThe longitude where the item was captured.
tags?array<>Tags to put on the item: at most 100, each up to 128 characters.
edges?Edges to create with the item, as edge type to a list of IDs of the items they point to. Each points from the new item. Marfa creates the item and all its edges, or none. When the request lands on an item by its natural key, each type you name replaces that item's edges of the type, and an edge to an ID you still list stays as it is. A new edge made this way carries no properties, so an edge type that requires one refuses the write.
Returns the existing item and its metadata:
source_idmatched a live item: Marfa updated it, or wrote nothing and setacknowledged: trueif that changed nothing.source_idmatched a trashed item: Marfa wrote nothing and setacknowledged: true.idrepeated a create you made: Marfa wrote nothing and setacknowledged: true, in any state.
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.
Returns the new item and its metadata.
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.
validation_error: a field is invalid or undeclared.missing_required_field:typeis missing.unknown_type:typeisn't registered.invalid_id:idor an ID an edge points to isn't valid.invalid_properties: the properties don't fit the type, or an inline edge lacks a property its type requires.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.
forbidden:sourceis not your credential's own or one of your key'ssources(details.sourcenames it), or the source allow-list excludes it.type_not_permitted: you don't have write on the item's type, or on the typesource_idresolves to.edge_type_not_permitted: you don't have write on an edge's type.
application/json- response
An error response.
error*What went wrong.
edge_type_not_found: an edge names an edge type that doesn't exist.item_not_found: an item an edge points to doesn't exist, or its type is one you can't read.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.
item_exists:create_onlyfound an item holding thesource_idorid.id_reused:idnames an item of another type, or one you can't read.link_taken: another item of the type holds this link.details.existing_idnames it.type_mismatch:source_idmatches an item of another type.version_conflict,ancestor_unavailable:versionis stale.
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 POST 'http://localhost:8600/items' \ -H 'Content-Type: application/json' \ -d '{ "type": "string"}'{ "item": { "id": "01a10119-55c0-77ac-9589-f7c48fa642b6", "type": "acme.deal", "state": "active", "tier": "library", "created_at": "2026-10-03T09:38:25.218Z", "updated_at": "2026-10-03T09:38:25.218Z", "last_activity_at": "2026-10-03T09:38:25.218Z", "occurred_at": "2026-10-03T09:38:25.218Z", "source": "crm", "source_id": "deal-1043", "version": 1, "schema_version": 1, "trashed_at": null, "read_only": false, "properties": { "name": "Pilot for Sample Ltd", "amount": 4500, "stage": "won" }, "edges": {} }, "metadata": { "item_id": "01a10119-55c0-77ac-9589-f7c48fa642b6", "tags": [], "extensions": {} }, "acknowledged": true}