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

Adopt

5 surfaces
Tools/Nodes/create_node

create_node

Create one entity, optionally with a parent edge. For 3+ entities, use `batch_create_nodes` instead of looping. Portfolio-scoped types (`portfolio`, `organization`, `product_area`) route to `.upg/portfolio.upg` rather than the active product's `nodes[]`.

Nodesatomic-with-rollback. Schema validation runs before mutation.

Arguments

typestringrequired

UPG entity type (e.g. "persona", "opportunity"). Portfolio-scoped: "portfolio", "organization", "product_area".

titlestringrequired

Entity title

descriptionstringoptional

Optional description

tagsarrayoptional

Freeform tags

statusstringoptional

Lifecycle status

propertiesobjectoptional

Type-specific fields

parent_idstringoptional

Parent node ID. Creates an edge automatically. Ignored for portfolio-scoped types.

keystringoptional

Optional citable key for this entity (e.g. "LTN-311"). Unique within the product across entity types, immutable once assigned, and never reused, so it is settable HERE and refused by update_node / batch_update_nodes. Supply one you already hold (an imported tracker key, or one your create surface chose); this tool never mints one for you.

archivedbooleanoptional

Sweep this entity out of default views. Orthogonal to `status`: an entity can be done and live, or done and archived, and those are different facts.

archived_atstringoptional

ISO timestamp archived. Pairs with `archived: true`.

overwrite_organizationbooleanoptional

For type="organization" only. When true, replaces the existing portfolio organisation instead of throwing.

Returns

Shape
{ node, edge?, unknown_properties?, warning? }
The edge field is present only when parent_id was supplied and a canonical hierarchy edge could be inferred.
unknown_properties and warning are present when the caller passed properties not in the entity's schema.
Pass strict: true to reject unknown properties instead of warning.
For portfolio-scoped types the response shape is { node, portfolio_file, written_to, warning? } where node is the persisted typed record.

Examples

Live call against the Notion example graph.

Input

{
  "type": "person",
  "title": "Example node"
}

Output

{
  "node": {
    "id": "n_lsZ0CjPWcrZ6Hhw8",
    "type": "person",
    "title": "Example node",
    "slug": "example-node"
  },
  "edge": null
}

See Also