Bulk upsert edges

curl --request POST \
  --url https://api.example.com/edges/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "edges": [
    {
      "source_id": "<string>",
      "target_id": "<string>",
      "edge_type": "<string>",
      "id": "<string>",
      "properties": {}
    }
  ],
  "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>"
      }
    }
  ]
}

Edges

Bulk upsert edges

Creates or upserts up to 5000 edges in one call. Sibling to POST /items/bulk for the graph half of tenant migrations — items created in an earlier bulk call exist on the server; a second pass through this endpoint wires them together without having to hold source and target in the same payload.

Modes: upsert (default) matches existing rows on (source_id, target_id, edge_type) and replaces properties in place; create_only surfaces matching rows as skipped with reason duplicate_edge. Atomic by default — any failure rolls back the batch. Set atomic: false to run per-edge with per-edge outcomes. emit_events: true fires an edge.created webhook per newly-created edge; updated outcomes emit nothing.

Admin-only. See Bulk operations for outcome shape and event semantics.

POST

edges

bulk

Bulk upsert edges

curl --request POST \
  --url https://api.example.com/edges/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "edges": [
    {
      "source_id": "<string>",
      "target_id": "<string>",
      "edge_type": "<string>",
      "id": "<string>",
      "properties": {}
    }
  ],
  "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

edges

object[]

required

Show child attributes

mode

enum<string>

Available options:

upsert,

create_only

atomic

boolean

emit_events

boolean

Response

Bulk edge result

counts

object

required

Show child attributes

results

object[]

required

Show child attributes

Update an edge List edge types

Documentation Index

Authorizations

Body

Response