Skip to content

Graph

Endpoints


POST /api/v1/repositories/{repoId}/graph/cypher

Execute a raw Cypher query against a repository's graph

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Request Body

FieldTypeRequiredDescription
querystringYesMin length: 1. Max length: 10000
paramsobjectNo
columnsobject[]No

Response (200)

FieldTypeRequiredDescription
rowsobject[]Yes
columnsstring[]Yes
row_countnumberYes

Error Responses

StatusDescription
400Invalid query
401Unauthorized
403Forbidden
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  -X POST \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/cypher" \
  -H "Authorization: Bearer $NEXGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "MATCH (f:Function) RETURN f.name, f.file_path LIMIT 10",
  "params": {},
  "columns": [
    {
      "name": "my-project"
    }
  ]
}'

Response:

json
{
  "rows": [
    {}
  ],
  "columns": [
    "string"
  ],
  "row_count": 1
}

GET /api/v1/repositories/{repoId}/graph/nodes

List and filter graph nodes

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Query Parameters

ParameterTypeRequiredDefaultDescription
labelstringNo
file_pathstringNo
exportedstringNo
limitintegerNo50
offsetinteger,nullNo0

Response (200)

FieldTypeRequiredDescription
nodesobject[]Yes
countnumberYes

Error Responses

StatusDescription
400Invalid filter parameters
401Unauthorized
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/nodes?label=value&file_path=value" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "nodes": [
    {
      "id": 1,
      "label": "ci-read-only",
      "properties": {}
    }
  ],
  "count": 1
}

GET /api/v1/repositories/{repoId}/graph/nodes/{nodeId}

Get a single node with all its relationships

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring
nodeIdstring

Response (200)

FieldTypeRequiredDescription
nodeobjectYes
relationshipsobjectYes

Error Responses

StatusDescription
400Invalid node ID
401Unauthorized
404Repository or node not found

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/nodes/<nodeId>" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "node": {
    "id": 1,
    "label": "ci-read-only",
    "properties": {}
  },
  "relationships": {
    "outgoing": [
      {
        "edge": {
          "id": 1,
          "label": "ci-read-only",
          "start_id": 1,
          "end_id": 1,
          "properties": {}
        },
        "source": {
          "id": 1,
          "label": "ci-read-only",
          "properties": {}
        },
        "target": {
          "id": 1,
          "label": "ci-read-only",
          "properties": {}
        }
      }
    ],
    "incoming": [
      {
        "edge": {
          "id": 1,
          "label": "ci-read-only",
          "start_id": 1,
          "end_id": 1,
          "properties": {}
        },
        "source": {
          "id": 1,
          "label": "ci-read-only",
          "properties": {}
        },
        "target": {
          "id": 1,
          "label": "ci-read-only",
          "properties": {}
        }
      }
    ]
  }
}

GET /api/v1/repositories/{repoId}/graph/edges

List and filter graph edges

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Query Parameters

ParameterTypeRequiredDefaultDescription
typestringNo
source_labelstringNo
limitintegerNo50

Response (200)

FieldTypeRequiredDescription
edgesobject[]Yes
countnumberYes

Error Responses

StatusDescription
400Invalid filter parameters
401Unauthorized
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/edges?type=value&source_label=value" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "edges": [
    {
      "edge": {
        "id": 1,
        "label": "ci-read-only",
        "start_id": 1,
        "end_id": 1,
        "properties": {}
      },
      "source": {
        "id": 1,
        "label": "ci-read-only",
        "properties": {}
      },
      "target": {
        "id": 1,
        "label": "ci-read-only",
        "properties": {}
      }
    }
  ],
  "count": 1
}

POST /api/v1/repositories/{repoId}/graph/impact

Analyze the blast radius of a symbol change

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Request Body

FieldTypeRequiredDescription
symbolstringYesMin length: 1. Max length: 500
direction"callers" | "callees" | "both"NoDefault: "both"
depthintegerNoDefault: 3. Min: 1. Max: 10
file_pathstringNo

Response (200)

FieldTypeRequiredDescription
rootobjectYes
affectedobject[]Yes
summaryobjectYes

Error Responses

StatusDescription
400Invalid request
401Unauthorized
403Forbidden
404Repository, graph, or symbol not found

Example

Request:

bash
curl -s \
  -X POST \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/impact" \
  -H "Authorization: Bearer $NEXGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "symbol": "handleRequest",
  "direction": "callers",
  "depth": 3,
  "file_path": "src/index.ts"
}'

Response:

json
{
  "root": {
    "id": 1,
    "label": "ci-read-only",
    "properties": {}
  },
  "affected": [
    {
      "id": 1,
      "label": "ci-read-only",
      "name": "my-project",
      "file_path": "src/index.ts",
      "relationship_type": "string",
      "properties": {}
    }
  ],
  "summary": {
    "total_affected": 1,
    "by_relationship_type": {}
  }
}

POST /api/v1/repositories/{repoId}/graph/dependencies

Query file-level or symbol-level dependency trees

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Request Body

FieldTypeRequiredDescription
file_pathstringNo
symbolstringNoMin length: 1. Max length: 500
depthintegerNoDefault: 1. Min: 1. Max: 10

Response (200)

Error Responses

StatusDescription
400Invalid request — must provide file_path or symbol
401Unauthorized
403Forbidden
404Repository, graph, file, or symbol not found

Example

Request:

bash
curl -s \
  -X POST \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/dependencies" \
  -H "Authorization: Bearer $NEXGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_path": "src/index.ts",
  "symbol": "handleRequest",
  "depth": 1
}'

Response:

json
{
  "type": "file",
  "root": {
    "id": 1,
    "label": "ci-read-only",
    "properties": {}
  },
  "imports": [
    {
      "id": 1,
      "label": "ci-read-only",
      "name": "my-project",
      "file_path": "src/index.ts",
      "properties": {}
    }
  ],
  "imported_by": [
    {
      "id": 1,
      "label": "ci-read-only",
      "name": "my-project",
      "file_path": "src/index.ts",
      "properties": {}
    }
  ]
}

POST /api/v1/repositories/{repoId}/graph/path

Find the shortest path between two symbols

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Request Body

FieldTypeRequiredDescription
fromstringYesMin length: 1. Max length: 500
tostringYesMin length: 1. Max length: 500
max_depthintegerNoDefault: 5. Min: 1. Max: 10
from_file_pathstringNo
to_file_pathstringNo

Response (200)

FieldTypeRequiredDescription
nodesobject[]Yes
edgesobject[]Yes
lengthnumberYes

Error Responses

StatusDescription
400Invalid request
401Unauthorized
403Forbidden
404Repository, graph, or symbol not found

Example

Request:

bash
curl -s \
  -X POST \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/path" \
  -H "Authorization: Bearer $NEXGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "UserService",
  "to": "DatabasePool",
  "max_depth": 5,
  "from_file_path": "src/services/user.ts",
  "to_file_path": "src/db/pool.ts"
}'

Response:

json
{
  "nodes": [
    {
      "id": 1,
      "label": "ci-read-only",
      "properties": {}
    }
  ],
  "edges": [
    {
      "id": 1,
      "label": "ci-read-only",
      "start_id": 1,
      "end_id": 1,
      "properties": {}
    }
  ],
  "length": 1
}

GET /api/v1/repositories/{repoId}/graph/stats

Get node and edge counts by type

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Response (200)

FieldTypeRequiredDescription
nodesobjectYes
edgesobjectYes
total_nodesnumberYes
total_edgesnumberYes

Error Responses

StatusDescription
401Unauthorized
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/stats" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "nodes": {},
  "edges": {},
  "total_nodes": 1,
  "total_edges": 1
}

GET /api/v1/repositories/{repoId}/graph/orphans

Find unreferenced symbols (no incoming edges)

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Query Parameters

ParameterTypeRequiredDefaultDescription
labelstringNo
limitintegerNo100
offsetinteger,nullNo0

Response (200)

FieldTypeRequiredDescription
orphansobject[]Yes
countnumberYes

Error Responses

StatusDescription
400Invalid filter parameters
401Unauthorized
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/orphans?label=value&limit=100" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "orphans": [
    {
      "id": 1,
      "label": "ci-read-only",
      "name": "my-project",
      "file_path": "src/index.ts",
      "properties": {}
    }
  ],
  "count": 1
}

GET /api/v1/repositories/{repoId}/graph/routes

List all HTTP route handlers in the repository

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstring

Response (200)

FieldTypeRequiredDescription
routesobject[]Yes
countnumberYes

Error Responses

StatusDescription
401Unauthorized
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/routes" \
  -H "Authorization: Bearer $NEXGRAPH_KEY"

Response:

json
{
  "routes": [
    {
      "http_method": "string",
      "url_pattern": "string",
      "framework": "string",
      "handler_name": "string",
      "file_path": "src/index.ts",
      "start_line": 1
    }
  ],
  "count": 1
}

POST /api/v1/repositories/{repoId}/graph/architecture

Check for architectural layer violations

Defines architectural layers by file path globs and deny rules, then queries the knowledge graph for CALLS and IMPORTS edges that cross forbidden layer boundaries.

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID

Request Body

FieldTypeRequiredDefaultDescription
layersobjectNoMap of layer name to file glob pattern (e.g., {"domain": "src/domain/**"})
rulesobject[]NoArray of deny rules (see below)
savebooleanNofalsePersist layers/rules to project settings for future use
edge_typesstring[]No["IMPORTS", "CALLS"]Edge types to check (IMPORTS, CALLS, or both)

If layers and rules are omitted, the endpoint falls back to previously saved settings in the project's settings.architecture_layers field.

Deny Rule Schema:

FieldTypeRequiredDescription
fromstringYesLayer name that the rule applies to
denystring[]YesLayer names that from must not depend on

Response (200)

FieldTypeDescription
violationsobject[]Array of detected violations
summaryobjectAggregate statistics

Violation object:

FieldTypeDescription
rulestringHuman-readable rule description (e.g., "domain → infrastructure (denied)")
source_filestringFile path of the violating source
source_symbolstringSymbol name in the source file
target_filestringFile path of the forbidden target
target_symbolstringSymbol name in the target file
edge_typestringCALLS or IMPORTS
linenumber | nullLine number of the source symbol

Summary object:

FieldTypeDescription
total_violationsnumberTotal number of violations found
rules_checkednumberNumber of deny rules evaluated
layers_foundnumberNumber of layers with classified files
files_classifiedobjectMap of layer name to file count

Error Responses

StatusDescription
400No layers/rules provided and none saved in project settings
401Unauthorized
403Forbidden
404Repository not found or has no graph

Example

Request:

bash
curl -s \
  -X POST \
  "http://localhost:3000/api/v1/repositories/$REPO_ID/graph/architecture" \
  -H "Authorization: Bearer $NEXGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "layers": {
    "controllers": "src/controllers/**",
    "services": "src/services/**",
    "domain": "src/domain/**",
    "infrastructure": "src/infrastructure/**"
  },
  "rules": [
    { "from": "domain", "deny": ["infrastructure", "controllers"] },
    { "from": "controllers", "deny": ["infrastructure"] }
  ],
  "save": false,
  "edge_types": ["IMPORTS", "CALLS"]
}'

Response:

json
{
  "violations": [
    {
      "rule": "domain → infrastructure (denied)",
      "source_file": "src/domain/User.ts",
      "source_symbol": "UserService",
      "target_file": "src/infrastructure/db.ts",
      "target_symbol": "query",
      "edge_type": "CALLS",
      "line": 15
    }
  ],
  "summary": {
    "total_violations": 1,
    "rules_checked": 2,
    "layers_found": 4,
    "files_classified": {
      "controllers": 5,
      "services": 3,
      "domain": 4,
      "infrastructure": 2
    }
  }
}

GET /api/v1/repositories/{repoId}/graph/communities

List detected communities with pagination

Communities are functional clusters of symbols detected via CALLS edges using the Leiden algorithm.

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID

Query Parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo50Max results
offsetintegerNo0Pagination offset

Response (200)

FieldTypeRequiredDescription
communitiesobject[]YesArray of community objects
countnumberYesTotal number of communities

Each community object includes: community_id, label, heuristic_label, cohesion, symbol_count, keywords.

Error Responses

StatusDescription
401Unauthorized
404Repository not found or has no graph

GET /api/v1/repositories/{repoId}/graph/communities/{communityId}

Get a specific community with its members

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID
communityIdstringCommunity ID

Response (200)

FieldTypeRequiredDescription
communityobjectYesCommunity metadata
membersobject[]YesArray of member symbols

Each member includes: name, label, file_path, line.

Error Responses

StatusDescription
401Unauthorized
404Repository or community not found

GET /api/v1/repositories/{repoId}/graph/processes

List detected processes with pagination and type filter

Processes are execution flows traced from entry points through CALLS edges via BFS.

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID

Query Parameters

ParameterTypeRequiredDefaultDescription
typestringNoFilter by intra_community or cross_community
limitintegerNo50Max results
offsetintegerNo0Pagination offset

Response (200)

FieldTypeRequiredDescription
processesobject[]YesArray of process objects
countnumberYesTotal number of processes

Each process includes: process_id, label, heuristic_label, process_type, step_count, entry_point_name, terminal_name.

Error Responses

StatusDescription
401Unauthorized
404Repository not found or has no graph

GET /api/v1/repositories/{repoId}/graph/processes/{processId}

Get a specific process with its ordered steps

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID
processIdstringProcess ID

Response (200)

FieldTypeRequiredDescription
processobjectYesProcess metadata
stepsobject[]YesOrdered array of step symbols

Each step includes: step (order), name, label, file_path.

Error Responses

StatusDescription
401Unauthorized
404Repository or process not found

POST /api/v1/repositories/{repoId}/graph/diff-impact

Analyze git diff impact on graph symbols and processes

Maps changed files to affected symbols, traces impact through the call graph, and identifies affected processes with risk assessment.

Authentication

Requires Bearer token. See Authentication.

Path Parameters

ParameterTypeDescription
repoIdstringRepository UUID

Request Body

FieldTypeRequiredDefaultDescription
scope"unstaged" | "staged" | "all" | "compare"No"all"Diff scope
compare_refstringNoGit ref to compare against HEAD (required when scope is "compare")
max_depthintegerNo3Max depth for indirect impact tracing (1–10)

Response (200)

FieldTypeRequiredDescription
changed_filesobject[]YesFiles detected as changed
direct_symbolsobject[]YesSymbols directly in changed files
impacted_symbolsobject[]YesSymbols affected via call graph traversal
affected_processesobject[]YesProcesses containing affected symbols
riskstringYesRisk level: LOW, MEDIUM, HIGH, or CRITICAL
summaryobjectYesAggregate counts

Error Responses

StatusDescription
400Invalid request or repository is not local_path type
401Unauthorized
404Repository not found or has no graph

Released under the MIT License.