Graph Edges

What you'll learn

Create typed, directional edges between agents, and query connected agents.

What graph edges are for

Agents are nodes. Edges express relationships: - users → orders (a user has orders) - orders → payments (an order has payments) - users → sessions (a user has sessions)

These are structural links stored in the graph layer — separate from the strand records.

Create an edge

curl -s -X POST http://localhost:7475/v1/graph/edges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{
    "from_agent": "users",
    "to_agent":   "orders",
    "edge_type":  "has_orders",
    "meta":       {"established": "2026-07-09"}
  }' | python3 -m json.tool

List edges from an agent

curl -s "http://localhost:7475/v1/graph/edges?from=users" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

List edges to an agent

curl -s "http://localhost:7475/v1/graph/edges?to=orders" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Delete an edge

curl -s -X DELETE "http://localhost:7475/v1/graph/edges/users/orders/has_orders" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"

Authorization (added 2026-09-21)

POST/GET /v1/graph/edges and DELETE /v1/graph/edges/:src/:type/:dst require the root key or a scoped key holding admin:graph — creating or deleting an edge reveals or changes structural links between agents platform-wide, so it's treated as cluster-wide configuration, not a per-tenant operation.

Challenge

Model this graph: company → departments → employees → time_entries. Create the three edges. List them to confirm the structure.

---