Query: Traverse

Traverse the graph from a node up to a specified depth.

method · POST

/query

Authentication: Required (if enabled)

BFS traversal from a starting node. Optionally filter by minimum edge weight.

Standard Traverse

{
  "type": "traverse",
  "node_id": 0,
  "depth": 3
}

Field	Type	Required	Constraints	Description
type	string	Yes	"traverse"	—
node_id	integer (u64)	Yes	—	Starting node.
depth	integer	Yes	0-100	Maximum traversal depth.

Filtered Traverse

Include only edges above a minimum weight, and optionally limit to the K highest-weight results:

{
  "type": "traverse_filtered",
  "node_id": 0,
  "depth": 3,
  "min_weight": 10,
  "top_k": 5
}

Use min_weight: 10 to traverse only stable edges — connections reinforced by at least 10 independent signals. This aligns with the stability threshold used by Developmental Stages.

Field	Type	Required	Description
min_weight	integer (i64)	Yes	Minimum edge weight to include.
top_k	integer	No	If set and > 0, return only the K highest-weight edges. Edges are sorted by weight descending before truncation. Omit or set to 0 for no limit.

Response

200 OK (found)

{
  "success": true,
  "found": true,
  "path": [0, 1, 2],
  "edges": [
    {"from": 0, "to": 1, "weight": 10},
    {"from": 1, "to": 2, "weight": 5}
  ],
  "grounding": "inference",
  "error": null
}

When found is false, diagnostic explains why (e.g. node_not_found).

Examples

# Standard traverse
curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"type": "traverse", "node_id": 0, "depth": 3}'

# Filtered traverse (stable edges only, weight >= 10)
curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"type": "traverse_filtered", "node_id": 0, "depth": 3, "min_weight": 10}'

# Filtered traverse with top_k — limit to 5 highest-weight edges
curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"type": "traverse_filtered", "node_id": 0, "depth": 3, "min_weight": 0, "top_k": 5}'