Get Knowledge Topology

GET /knowledge-graph/topology

The shape of one base: what everything hangs off, and what it has never connected.

Two answers from one walk of the confirmed graph. hubs ranks the items by a weighted degree (the eight edge kinds are not worth the same, and a flat count would put whatever collected the most cheap relates_to edges at the top) and splits them into a principal and a secondary tier at one population deviation above the base’s own mean, which is a cut the base decides rather than a number in this file. gaps pairs the dense groups that have no confirmed relation between them and names, for each, the two items the embedding space already puts closest: the relation the base is missing, as something concrete to go and look at.

No model is called and none can be. The whole report is integer arithmetic over rows plus one cosine the database computes, which is why it is free, reproducible and safe to poll, exactly as GET /knowledge-health is.

There is no statuses parameter. Only confirmed edges count: a proposed relation is a suggestion the confirmation step has not accepted, and letting one close a gap would make this report answer “something already connects these” when nothing does.

Every ceiling has a flag. A shape drawn from a truncated graph is a different shape, and a reader who cannot tell will act on hubs that are not the base’s hubs.

Role floor

Requires viewer or above. The floor is a minimum, not a grant: scope filtering still applies on top of it, and a resource in another tenant answers 404 rather than 403.

Parameters

Name	In	Type		Notes
kb_id	query	string (uuid)	required	the base to measure
viewer_agent_id	query	string (uuid) | null	optional	read as this agent: unlocks its private bases

Responses

Status	Description	Body
200	Successful Response	KnowledgeTopologyView
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

curl -X GET https://your-deployment.example.com/knowledge-graph/topology \
  -H "Authorization: Bearer $COBRE_TOKEN"

Response — KnowledgeTopologyView

Field	Type		Notes
kb_id	string (uuid)	required	—
hubs	KnowledgeHubView[]	optional	—
cut	KnowledgeHubCut	optional	—
gaps	KnowledgeGapView[]	optional	—
edge_weights	object	optional	—
total_items	integer	optional	Default 0.
items_considered	integer	optional	Default 0.
confirmed_edges	integer	optional	Default 0.
groups_considered	integer	optional	Default 0.
truncated_at_item_limit	boolean	optional	Default false.
truncated_at_edge_limit	boolean	optional	Default false.
truncated_at_group_limit	boolean	optional	Default false.
truncated_at_gap_limit	boolean	optional	Default false.
truncated_at_bridge_candidate_limit	boolean	optional	Default false.