Skip to content
Joe Documentation
Guides
The knowledge graph

The knowledge graph

Joe keeps a graph of your infrastructure — services, clusters, the systems that hold their metrics and logs, and the relationships between them. This page covers how to query it and how it gets populated. For the model behind it, read The knowledge graph in Concepts.

Query the graph

Over HTTP:

  • GET /api/v1/graph/query?q=<text> — search for nodes matching a query string.
  • GET /api/v1/graph/related?nodeID=<id>&depth=<1-3> — find nodes related to one node.
  • GET /api/v1/graph/summary — node and edge counts.

The web UI renders the same graph (GET /api/v1/graph returns the full node-and-edge set, with GET /api/v1/graph/node/{id} and …/related for a single node), and the MCP tools joe_graph_query and joe_graph_related expose the same two queries to an editor.

curl -s "http://localhost:7777/api/v1/graph/query?q=payment-svc" \
  -H "Authorization: Bearer $JOE_API_KEY"

How the graph populates

You do not hand-author the graph node by node. It fills from two places:

  • Components you register. Registering a managed system (the register → promote flow in Components) puts it under Joe’s management. Registration alone is inert; once a component is promoted and armed, Joe’s autonomous refresh cycle connects to it.
  • Autonomous discovery. The refresh cycle reads each armed component, discovers the resources and relationships it exposes, and upserts the corresponding nodes and edges. Re-running refresh reconciles the graph against what the systems currently report — nodes and edges are upserted, not duplicated.

Observability backends are resolved through graph edges

This is the payoff of the graph. When you ask an observability question about a service, Joe does not need you to name the backend — it walks the graph edges from the service to the system that holds that signal. The edges are typed by signal: metrics_in, logs_in, traces_in, and alerts_in (with paged_via as a secondary alerting edge).

The category endpoints — POST /api/v1/observe/{metrics,logs,traces,alerts,k8s} — each resolve their backend by following the matching edge from the named service, then translate and run the query against whatever system that edge points to. The MCP tools joe_metrics, joe_logs, joe_traces, joe_alerts, and joe_k8s are the same surface from an editor. Connect the backing systems and wire their edges through Components and these resolve automatically.

Where to go next

The Slack bot