API Reference

Define an allowed connection pattern between node types for a relationship type. All three (relationship type, source node type, target node type) must already exist in the metamodel. Use get_metamodel to check existing types.

Add a new node type (entity type) to the metamodel. Do this before creating nodes of that type. You can define custom properties with data types. For simulation, a property can be marked computed (its default_value is then a Rhai formula evaluated each timestep), and the node type can carry an act_script — a Rhai script run per agent per timestep that drives behaviour.

Add a new relationship type to the metamodel. After creating it, use add_allowed_connection to specify which node types can be connected with it.

Auto-show all relationships between elements already placed on a diagram. For model diagrams shows M1 relationships; for metamodel diagrams shows allowed connections. Applied immediately.

Add nodes or node types to a diagram with auto-grid layout. For model diagrams use node IDs or auto-IDs (e.g. REQ-1); for metamodel diagrams use node type IDs. Applied immediately.

Clear a single baseline overlay value for an agent property in a parameter set (reverts to inheriting the default set). Applied immediately and broadcast to connected users in real-time.

Clear one time-series cell (an agent's property value at a timestep). Applied immediately and broadcast to connected users in real-time.

Create an agent instance in a scenario. node_type_id (the agent's type) is required and defines its property and behavior schema. Baseline properties may be keyed by name or ID and target the given (or twin-default) parameter set. Applied immediately and broadcast to connected users in real-time.

Create a new diagram for visualizing model elements. Use diagram_type 'metamodel' for M2 type diagrams, 'model' for M1 instance diagrams. Applied immediately.

Create a stored filter with a composable expression. Expressions: {"OfType":{"type_id":"<id>"}}, {"HasTag":{"tag":"foo"}}, {"NameMatches":{"operator":"Contains","value":"foo"}}, {"And":[...]}, {"Or":[...]}, {"Not":expr}, {"InFolder":{"folder_id":"<id>","recursive":true}}, or "All". Applied immediately.

Create a new folder for organizing model elements. Use layer 'metamodel' for node/relationship type folders, 'model' for node/relationship/diagram folders. Applied immediately.

Create a link between two agents in a scenario — the simulation counterpart of a relationship. The relationship type and both agents must already exist. Applied immediately and broadcast to connected users in real-time.

Create new node instances. Node type must already exist in the metamodel (use get_metamodel to check, or add_node_type to create). Changes are applied immediately and broadcast to all connected browser users in real-time.

3 parameter(s)

Create a parameter set within a twin — a named bundle of input-value overrides on an axis orthogonal to scenarios. Use a stable lowercase name (e.g. "high_demand"). Applied immediately and broadcast to connected users in real-time.

Create relationships between existing nodes. Both source and target must exist. The relationship type must exist in the metamodel and have an allowed connection defined for the given source/target node types.

Create a scenario (what-if projection) within a twin, with its own timeline. The step size dt must be 1/N for a positive integer N (e.g. 1, 0.5, 0.25). Applied immediately and broadcast to connected users in real-time.

Create a simulation diagram — a visual canvas for a scenario or twin. Provide exactly one of scenario_id (scenario-scoped) or twin_id (twin-level, spans all scenarios). Agent/link placement and widgets are added in-app. Applied immediately and broadcast to connected users in real-time.

Create a simulation twin — a Live Twin container scoped to a subset of node types, optionally attached to a model node. Scenarios, parameter sets, and agents are created inside it. Applied immediately and broadcast to connected users in real-time.

Delete an agent instance along with its links, time series, and diagram placements. Applied immediately and broadcast to connected users in real-time.

Delete a diagram and all its element placements. Does NOT delete the underlying nodes or relationships — only the visual representation. Applied immediately.

Delete a stored filter. Does not delete any model data. Applied immediately. Accepts filter ID or name.

Delete a link and its diagram placements. Applied immediately and broadcast to connected users in real-time.

Delete one or more nodes. By default, all connected relationships are also deleted (cascade). Set cascade_relationships to false to fail if the node has any relationships.

2 parameter(s)

Delete a parameter set along with its overlay values and time series. A twin's default parameter set cannot be deleted. Applied immediately and broadcast to connected users in real-time.

Delete one or more relationships by their IDs. Use get_relationships to find the relationship IDs first.

Delete a scenario along with its agents, links, and time series. Applied immediately and broadcast to connected users in real-time.

Delete a simulation diagram and its placements and widgets. Applied immediately and broadcast to connected users in real-time.

Delete a twin and everything inside it — its scenarios, parameter sets, agents, links, and time series. Applied immediately and broadcast to connected users in real-time.

Merge duplicate nodes into a single node. All relationships from merged nodes are redirected to the kept node. The merged nodes are then deleted. Use find_similar_nodes to identify candidates.

1 parameter(s)

Move model elements into a folder (or to root by omitting folder_id). Supports nodes, relationships, node types, relationship types, diagrams, and folders. Applied immediately.

Remove an allowed connection constraint, revoking permission for a relationship type to connect specific node type pairs. Applied immediately.

Remove nodes or node types from a diagram. Also removes connected relationship visualizations on that diagram. Does NOT delete the underlying elements. Applied immediately.

Remove a node type from the metamodel. Also cascades to remove all M1 instances of that type and their relationships. Applied immediately. Use with caution — cannot be undone via MCP.

Remove a relationship type from the metamodel. Also removes all relationships of that type from M1. Applied immediately. Use with caution.

Rename an existing folder and optionally update its description. Applied immediately.

Set a single baseline value for an agent property in a specific parameter set — the field a slider or checkbox would write. For per-timestep values use set_time_series_value. Applied immediately and broadcast to connected users in real-time.

Set one cell of the simulation spreadsheet: an agent's property value at a given timestep, in a scenario and parameter set. property_id may be a property name or ID; omit parameter_set_id for the twin default. Applied immediately and broadcast to connected users in real-time.

Update an agent's label, description, or baseline property overlay. set_properties replaces the entire overlay for the target parameter set — to change a single value use set_parameter_value instead. Applied immediately and broadcast to connected users in real-time.

Update an existing diagram's name or description. Applied immediately. Accepts diagram ID or name.

Update a link's description and/or property values (set_properties replaces the link's properties). Applied immediately and broadcast to connected users in real-time.

Update the model's top-level name or description. Applied immediately.

Update an existing node type: rename, recolor, change description, or add new properties. For simulation, set_act_script sets or clears the node type's Rhai act script, and update_properties edits existing properties in place — including making a property computed or changing its Rhai formula. Applied immediately and broadcast to all connected users.

Update labels, descriptions, or properties on existing nodes. Use set_label/set_description to update core fields, set_properties for key-value pairs, and remove_properties to clear values. Node IDs accept both UUIDs and auto-IDs (e.g. REQ-42).

1 parameter(s)

Update a parameter set's name and/or description. Applied immediately and broadcast to connected users in real-time.

Update an existing relationship type: rename, recolor, change description, or add new properties. Applied immediately and broadcast to all connected users.

Update labels, descriptions, or properties on existing relationships. Applied immediately and broadcast to all connected users. Relationship IDs accept both UUIDs and auto-IDs (e.g., "CON-5").

Update a scenario's name, description, or timeline (start time, end time, dt). A changed dt must still be 1/N for a positive integer N. Applied immediately and broadcast to connected users in real-time.

Update a simulation diagram's name and/or description. Applied immediately and broadcast to connected users in real-time.

Update tags on any model element (node, relationship, node type, relationship type, diagram, or folder). Replaces all existing tags. Applied immediately.

Update a twin's name and/or description. Applied immediately and broadcast to connected users in real-time.

Find nodes with similar names that might be duplicates. Uses string similarity matching. Useful before creating new nodes to avoid duplication.

3 parameter(s)

Get full details for agents by ID, including baseline property values grouped by parameter set (property names resolved from the agent's node type).

Get the model's schema (metamodel). Returns all node types, relationship types, their properties, allowed connections, and instance counts. Always call this first to understand what the model contains. For simulation models it also reports each property's computed flag and Rhai formula and each node type's act_script, plus a self-describing "scripting" block documenting the available simulation functions (get_connected, sum_prop, agent.get_prop/set_prop, …) so you can author formulas correctly.

1 parameter(s)

Get complete details for one or more nodes by their IDs. Returns all properties, description, and metadata. Accepts both UUIDs and auto-IDs (e.g. REQ-42). Each node also includes an updated_at timestamp (ISO 8601 UTC) marking when it last changed, so external tools can skip nodes that haven't changed since they last looked.

2 parameter(s)

Find relationships (connections) between nodes. Filter by relationship type, source node, target node, or node types. Source and target IDs accept both UUIDs and auto-IDs (e.g. REQ-42).

7 parameter(s)

Get the widgets on a simulation diagram (dashboard) with their IDs and current text — charts (name, axis labels, per-series display names) and slider/checkbox/option/text/parameter-set-chooser controls (label). These widgets live only on the diagram and have no model-tree presence, so this is the only way to discover their IDs. Use it to translate a dashboard: read the contents, then write translations with translate_elements using keys like '{chart_id}:name', '{chart_id}:series:{series_id}:display_name', and '{widget_id}:label'.

Get model-wide statistics: node and relationship counts by type, most connected nodes, and property completeness. Useful for a quick model overview.

1 parameter(s)

Read time-series values: an agent's property value at each timestep, for a scenario and parameter set. This is the simulation spreadsheet data. scenario_id is required; omit parameter_set_id to read across all parameter sets.

List agent instances in a scenario. Each agent is an instance of a node type living in one scenario. Returns summaries; use get_agent_details for baseline property values. Filter by scenario, twin, node type, or name.

List the model's diagrams with their IDs, names, and levels. Diagrams aren't returned by search_nodes, so this is how you discover a diagram's ID before calling update_diagram, add_to_diagram, add_relationships_to_diagram, remove_from_diagram, or delete_diagram. Filter by level (metamodel for type diagrams, model for instance diagrams), name, or folder. For simulation dashboards use list_simulation_diagrams instead.

List links — the connections between agents within a scenario (the simulation counterpart of relationships). Returns endpoints with resolved agent labels and link property values. Filter by scenario, relationship type, or endpoint.

List the parameter sets in a twin. A parameter set is a named bundle of input values on an axis orthogonal to scenarios — a simulation run is keyed by (scenario, parameter set). Shows which set is the twin's default.

List scenarios within twins. A scenario is a what-if projection with its own timeline (start time, end time, step size dt). Returns timeline parameters, the computed timestep count, and agent/link counts. Filter by twin_id.

List simulation diagrams — the visual canvases for a scenario or twin that show agents, links, and dashboard widgets. Filter by twin or scenario.

List simulation twins. A twin is a Live Twin container scoped to a subset of node types, optionally attached to a model node. Returns each twin's scope, default parameter set, and scenario/parameter-set counts.

Search for nodes (instances) in the model. Filter by type, name, description, property values, or folder. Returns summaries — use get_node_details for full information. Each summary now includes an updated_at timestamp (ISO 8601 UTC) for change detection.

8 parameter(s)