Bulk upsert items

curl --request POST \
  --url https://api.example.com/items/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "type": "<string>",
      "id": "<string>",
      "properties": {},
      "timestamp": "<string>",
      "source": "<string>",
      "source_id": "<string>",
      "device": "<string>",
      "tags": [
        "<string>"
      ],
      "edges": {}
    }
  ],
  "atomic": true,
  "emit_events": true
}
'

{
  "counts": {
    "created": 123,
    "updated": 123,
    "skipped": 123,
    "errored": 123
  },
  "results": [
    {
      "index": 123,
      "id": "<string>",
      "reason": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  ]
}

Items

Bulk upsert items

Creates or upserts up to 5000 items in one call. Use for tenant migrations, importer runs, replays of an external source. Replaces the historical /import endpoint.

Modes: upsert (default) matches existing rows on (source, source_id) and updates in place — properties shallow-merge, tags replace if provided, edges union-merge if provided; create_only surfaces matching rows as skipped. Atomic by default — atomic: true wraps the batch in one transaction; atomic: false runs per-item with per-item outcomes. emit_events: false is the default; opt in with emit_events: true if subscribers should fan out per item.

Inline edges blocks on items have replace-all-per-type semantics within the batch. For cross-batch edges, use POST /edges/bulk after items land.

Admin-only. source is server-stamped from the credential — any caller-supplied source is silently overwritten. See Bulk operations.

POST

items

bulk

Bulk upsert items

curl --request POST \
  --url https://api.example.com/items/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "type": "<string>",
      "id": "<string>",
      "properties": {},
      "timestamp": "<string>",
      "source": "<string>",
      "source_id": "<string>",
      "device": "<string>",
      "tags": [
        "<string>"
      ],
      "edges": {}
    }
  ],
  "atomic": true,
  "emit_events": true
}
'

{
  "counts": {
    "created": 123,
    "updated": 123,
    "skipped": 123,
    "errored": 123
  },
  "results": [
    {
      "index": 123,
      "id": "<string>",
      "reason": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Body

application/json

items

object[]

required

Show child attributes

mode

enum<string>

Available options:

upsert,

create_only

atomic

boolean

emit_events

boolean

Response

Bulk upsert result

counts

object

required

Show child attributes

results

object[]

required

Show child attributes

Remove a tag from an item Apply a bulk action

Documentation Index

Authorizations

Body

Response