Update an item

curl --request PATCH \
  --url https://api.example.com/items/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "properties": {},
  "version": 1,
  "force_snapshot": true,
  "timestamp": "<string>",
  "source_id": "<string>",
  "edges": {}
}
'

{
  "item": {
    "id": "<string>",
    "type": "<string>",
    "properties": {},
    "version": 123,
    "schema_version": 123,
    "source": "<string>",
    "timestamp": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "tenant_id": "<string>",
    "source_id": "<string>",
    "device": "<string>",
    "capture_latitude": 123,
    "capture_longitude": 123,
    "edges": {},
    "extensions": {}
  },
  "metadata": {
    "item_id": "<string>",
    "tags": [
      "<string>"
    ],
    "extensions": {}
  }
}

Items

Update an item

Updates an item’s properties, tier, timestamp, or natural-key source_id. Properties shallow-merge into the existing row (unmentioned keys keep their values). The optional version field enables optimistic concurrency — pass the version the caller is editing from; a mismatch returns 409 version_conflict with the three-way context (current, ancestor, conflicting fields, resolved merge policy) the client needs to resolve. See Conflicts and Errors — version_conflict.

The edges block has replace-all-for-specified-types semantics: any edge_type listed wipes existing outbound edges of that type from this item, then creates new edges to each listed target. Empty array for an edge_type deletes all edges of that type. Unmentioned edge types are untouched.

Tier and timestamp updates are last-writer-wins and never produce a version conflict.

The source_id field repoints the item at a new natural key under the item’s source. The (source, source_id) tuple is unique per tenant — collisions with a different existing item return 409 source_id_conflict. PATCHing the value the item already carries is a no-op success. Used by the sync agent to preserve item identity through file renames.

PATCH

items

{id}

Update an item

curl --request PATCH \
  --url https://api.example.com/items/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "properties": {},
  "version": 1,
  "force_snapshot": true,
  "timestamp": "<string>",
  "source_id": "<string>",
  "edges": {}
}
'

{
  "item": {
    "id": "<string>",
    "type": "<string>",
    "properties": {},
    "version": 123,
    "schema_version": 123,
    "source": "<string>",
    "timestamp": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "tenant_id": "<string>",
    "source_id": "<string>",
    "device": "<string>",
    "capture_latitude": 123,
    "capture_longitude": 123,
    "edges": {},
    "extensions": {}
  },
  "metadata": {
    "item_id": "<string>",
    "tags": [
      "<string>"
    ],
    "extensions": {}
  }
}

Authorizations

Authorization

string

header

required

Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)

Path Parameters

string

required

Body

application/json

properties

object

Show child attributes

version

integer

Required range: x >= 0

force_snapshot

boolean

tier

enum<string>

Available options:

library,

feed

timestamp

string

source_id

string

edges

object

Show child attributes

Response

Item updated

item

object

required

Show child attributes

metadata

object

required

Show child attributes

Soft delete an item Restore a trashed item

Documentation Index

Authorizations

Path Parameters

Body

Response