UPG is in early alpha. The specification is still evolving and may change between versions.

Adopt

5 surfaces
Tools/Nodes/batch_create_nodes

batch_create_nodes

Create up to 50 entities in one atomic call, optionally with explicit edges in the same transaction. Reference earlier nodes from `parent_ref` / `edges` by a positional `$N` ("$0", "$1") OR by a batch-local `ref` alias declared on a node (e.g. ref:"persona_dev" then from_ref:"persona_dev"); aliases remove the index-counting that most often breaks a batch. `edges` endpoints also accept existing node IDs. All nodes and edges validate up front; on failure nothing lands and the response carries the full `errors` list plus the alias `ref_map`. Pass `validate_only: true` for a dry-run that reports every would-be error WITHOUT writing.

Nodesatomic-with-rollback. Full validation pass first, then commit. `validate_only` never mutates.

Arguments

nodesarrayrequired

Array of nodes to create (max 50)

edgesarrayoptional

Optional edges to create alongside the nodes (same atomic transaction). Each edge's from/to may be a `$N` ref into the `nodes` array, a declared `ref` alias, OR an existing node ID.

validate_onlybooleanoptional

Dry-run: run the full validation pass and report `{ valid, errors, would_create_nodes, would_create_edges }` WITHOUT writing. Lets an agent self-correct the whole batch before committing.

expect_productstringoptional

Optional guard: abort if the active product is not this id/title/file. Cheap insurance against a forgotten switch_product writing into the wrong graph.

Returns

JSON: on commit, { created, edges, explicit_edges?, count, warnings? }.
On validate_only, { validate_only, valid, errors, would_create_nodes, would_create_edges, ref_map?, warnings? }.
On a failed commit, a { error, errors?, ref_map? } error envelope.

Examples

Live call against the Notion example graph.

Input

{
  "nodes": [
    {
      "type": "person",
      "title": "Example node A"
    },
    {
      "type": "person",
      "title": "Example node B"
    }
  ]
}

Output

{
  "created": [
    {
      "id": "n_psZXNbg3DydBoRqy",
      "type": "person",
      "title": "Example node A"
    },
    {
      "id": "n_UJalQ1iIh93K5eJ9",
      "type": "person",
      "title": "Example node B"
    }
  ],
  "edges": [],
  "count": 2,
  "warnings": [
    "Created 2 nodes with no edges; they are orphans. Use the edges[] array in this call to link them. See get_entity_schema(<type>) for canonical edges per type."
  ]
}

See Also