Items

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.

POST
/items

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

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
type*string

The 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?string

A 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?string

The item's first lifecycle state, one the type's lifecycle can reach. Defaults to active.

occurred_at?string

When the item occurred, as an ISO 8601 time. Defaults to the creation time.

source?string

The 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?string

The 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?string

upsert (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.

Value in"upsert""create_only"
version?integer

The 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.

Range0 <= value
tier?string

The 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.

Value in"library""feed"
capture_latitude?number

The latitude where the item was captured.

capture_longitude?number

The 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.

Response body

About errors

Returns the existing item and its metadata:

  • source_id matched a live item: Marfa updated it, or wrote nothing and set acknowledged: true if that changed nothing.
  • source_id matched a trashed item: Marfa wrote nothing and set acknowledged: true.
  • id repeated a create you made: Marfa wrote nothing and set acknowledged: true, in any state.
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.

Returns the new item and its metadata.

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.

  • validation_error: a field is invalid or undeclared.
  • missing_required_field: type is missing.
  • unknown_type: type isn't registered.
  • invalid_id: id or 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
  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.

  • forbidden: source is not your credential's own or one of your key's sources (details.source names it), or the source allow-list excludes it.
  • type_not_permitted: you don't have write on the item's type, or on the type source_id resolves to.
  • edge_type_not_permitted: you don't have write on an edge's type.
application/json
  1. 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_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.

  • item_exists: create_only found an item holding the source_id or id.
  • id_reused: id names an item of another type, or one you can't read.
  • link_taken: another item of the type holds this link. details.existing_id names it.
  • type_mismatch: source_id matches an item of another type.
  • version_conflict, ancestor_unavailable: version is stale.
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 POST 'http://localhost:8600/items' \  -H 'Content-Type: application/json' \  -d '{  "type": "string"}'
About errors
{  "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}