Code Finder endpoints — BugViper API

GET /api/v1/query/code-finder/* endpoints find functions, classes, variables, modules, imports by name and return cyclomatic complexity metrics.

The Code Finder endpoints provide precise, targeted lookup into the knowledge graph. Unlike the unified search endpoint, each Code Finder route targets a specific node type (function, class, variable, module, import) or capability (file peeking, complexity analysis). Use these endpoints when you already know what kind of symbol you are looking for, or when you need to inspect a specific line range in a file stored in the graph.

---

GET /api/v1/query/code-finder/function

Finds function nodes by name. Supports exact and fuzzy matching.

name · string · required

Function name to search for.

fuzzy · boolean · default: "false"

Enable fuzzy matching to find functions with similar names.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

Response

function_name · string

The query name.

fuzzy_search · boolean

Whether fuzzy matching was enabled.

results · object[]

Matching function nodes with name, path, line_number, and source_code.

total · number

Number of matches returned.

---

GET /api/v1/query/code-finder/class

Finds class nodes by name. Supports exact and fuzzy matching.

name · string · required

Class name to search for.

fuzzy · boolean · default: "false"

Enable fuzzy matching.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

Response

class_name · string

The query name.

fuzzy_search · boolean

Whether fuzzy matching was enabled.

results · object[]

Matching class nodes.

total · number

Number of matches returned.

---

GET /api/v1/query/code-finder/variable

Finds variable nodes whose name contains the given substring.

name · string · required

Variable name or substring to search for.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

---

GET /api/v1/query/code-finder/content

Finds functions, classes, and variables whose source code contains a given pattern. Useful when you remember a code pattern but not the symbol name.

query · string · required

Pattern to match against the source_code property of graph nodes.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

---

GET /api/v1/query/code-finder/module

Finds module nodes by name. Module nodes represent files or packages as stored in the graph.

name · string · required

Module name to search for.

---

GET /api/v1/query/code-finder/imports

Finds import statement nodes by import name or alias.

name · string · required

Import name or alias to search for (e.g. fastapi, APIRouter, np).

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

---

GET /api/v1/query/code-finder/peek

Returns a window of lines from a file stored in the graph, centered on an anchor line. Use this endpoint to view context around a result from code-finder/line or any endpoint that returns a path and line_number.

path · string · required

File path as stored in the graph. This is the absolute or repo-relative path recorded during ingestion.

line · number

Anchor line number (1-indexed). Defaults to 1 if omitted. The anchor line is flagged with is_anchor: true in the response.

above · number · default: "10"

Number of lines to include above the anchor. Maximum 200.

below · number · default: "10"

Number of lines to include below the anchor. Maximum 200.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

Response

lines · object[]

Array of line objects in the requested window.

Show line properties

line_number · number

1-indexed line number in the file.

content · string

Source text of the line.

is_anchor · boolean

true for the line matching the line parameter, false for surrounding context lines.

Example

curl "https://your-bugviper-instance/api/v1/query/code-finder/peek?path=api/routers/ingestion.py&line=34&above=5&below=10&repo_owner=acme-corp&repo_name=my-api" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

---

GET /api/v1/query/code-finder/complexity

Returns the cyclomatic complexity score and risk level for a specific function.

function_name · string · required

Name of the function to analyze.

path · string

Optional file path filter. Use this when multiple functions share the same name across different files.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

Response

function_name · string

The queried function name.

path_filter · string

The path filter applied, or null.

complexity · object

Complexity result including the numeric score and a risk level label.

Error responses

Status	Cause
404	No function with that name (and optional path) was found in the graph.

---

GET /api/v1/query/code-finder/complexity/top

Returns the top N most complex functions across the graph, ranked by cyclomatic complexity score in descending order. Use this to identify the highest-risk functions in a codebase.

limit · number · default: "10"

Number of functions to return.

repo_owner · string

Filter to a specific repository owner.

repo_name · string

Filter to a specific repository name.

Response

limit · number

The requested limit.

results · object[]

Functions ranked by complexity score, highest first. Each object includes name, path, line_number, complexity score, and risk level.

total · number

Number of results returned.

Example

curl "https://your-bugviper-instance/api/v1/query/code-finder/complexity/top?limit=5&repo_owner=acme-corp&repo_name=my-api" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

{
  "limit": 5,
  "results": [
    {
      "name": "ingest_github_repository",
      "path": "ingestion_service/core/repo_ingestion_engine.py",
      "line_number": 88,
      "complexity": 24,
      "risk_level": "high"
    },
    {
      "name": "_handle_comment_review",
      "path": "api/routers/webhook.py",
      "line_number": 160,
      "complexity": 15,
      "risk_level": "medium"
    }
  ],
  "total": 2
}