Graph Queries

The graph API exposes the Neo4j knowledge graph through structured endpoints for navigating call relationships, tracing dependencies, detecting cycles, and understanding data flow.

Get callers

GET /v1/repos/{repo_id}/graph/callers/{fqn}

Returns symbols that call the specified symbol, traversing up the call graph.

Parameter	Type	In	Description
repo_id	string	path	Repository ID
fqn	string	path	Fully qualified name of the target symbol
depth	integer	query	Maximum traversal depth (default 3, max 10)

Response

{
  "root": "com.example.UserService.findById",
  "nodes": [
    {
      "fqn": "com.example.UserController.getUser",
      "file_path": "src/main/java/com/example/UserController.java",
      "kind": "method",
      "depth": 1
    },
    {
      "fqn": "com.example.AdminController.lookupUser",
      "file_path": "src/main/java/com/example/AdminController.java",
      "kind": "method",
      "depth": 2
    }
  ],
  "edges": [
    {
      "from": "com.example.UserController.getUser",
      "to": "com.example.UserService.findById",
      "type": "call"
    },
    {
      "from": "com.example.AdminController.lookupUser",
      "to": "com.example.UserController.getUser",
      "type": "call"
    }
  ]
}

Get callees

GET /v1/repos/{repo_id}/graph/callees/{fqn}

Returns symbols that the specified symbol calls, traversing down the call graph.

Parameter	Type	In	Description
repo_id	string	path	Repository ID
fqn	string	path	Fully qualified name of the source symbol
depth	integer	query	Maximum traversal depth (default 3, max 10)

The response format is identical to Get callers, with edges pointing from the root outward.

Find call path

GET /v1/repos/{repo_id}/graph/path

Finds the shortest call path between two symbols in the graph.

Parameter	Type	In	Description
repo_id	string	path	Repository ID
from	string	query	FQN of the source symbol
to	string	query	FQN of the target symbol

Response

{
  "from": "com.example.UserController.getUser",
  "to": "com.example.UserRepository.findById",
  "path": [
    "com.example.UserController.getUser",
    "com.example.UserService.findById",
    "com.example.UserRepository.findById"
  ],
  "edges": [
    {
      "from": "com.example.UserController.getUser",
      "to": "com.example.UserService.findById",
      "type": "call"
    },
    {
      "from": "com.example.UserService.findById",
      "to": "com.example.UserRepository.findById",
      "type": "call"
    }
  ]
}

Returns an empty path array if no path exists between the two symbols.

Get module dependencies

GET /v1/repos/{repo_id}/graph/deps/{module_path}

Returns the dependency graph for a module or package.

Parameter	Type	In	Description
repo_id	string	path	Repository ID
module_path	string	path	Module or package path (e.g. pkg/auth, com.example.service)
direction	string	query	upstream (who depends on this) or downstream (what this depends on). Default: downstream
depth	integer	query	Maximum traversal depth (default 2, max 5)

Response

{
  "root": "com.example.service",
  "direction": "downstream",
  "nodes": [
    {
      "module": "com.example.repository",
      "depth": 1
    },
    {
      "module": "com.example.model",
      "depth": 1
    }
  ],
  "edges": [
    {
      "from": "com.example.service",
      "to": "com.example.repository",
      "type": "import"
    },
    {
      "from": "com.example.service",
      "to": "com.example.model",
      "type": "import"
    }
  ]
}

Detect dependency cycles

GET /v1/repos/{repo_id}/graph/cycles

Detects circular dependencies in the module graph.

Parameter	Type	In	Description
repo_id	string	path	Repository ID

Response

{
  "cycles": [
    {
      "modules": [
        "com.example.service",
        "com.example.repository",
        "com.example.service"
      ],
      "length": 2
    }
  ],
  "total": 1
}

Returns an empty cycles array if no circular dependencies are found.

Trace data flow

GET /v1/repos/{repo_id}/graph/dataflow/{fqn}

Traces how data flows through function parameters and return values starting from the specified symbol.

Parameter	Type	In	Description
repo_id	string	path	Repository ID
fqn	string	path	Fully qualified name of the symbol to trace

Response

{
  "root": "com.example.UserService.findById",
  "facts": [
    {
      "source_fqn": "com.example.UserController.getUser",
      "target_fqn": "com.example.UserService.findById",
      "parameter": "id",
      "type": "argument_pass"
    },
    {
      "source_fqn": "com.example.UserService.findById",
      "target_fqn": "com.example.UserRepository.findById",
      "parameter": "id",
      "type": "argument_pass"
    },
    {
      "source_fqn": "com.example.UserRepository.findById",
      "target_fqn": "com.example.UserService.findById",
      "parameter": "return",
      "type": "return_value"
    }
  ]
}