Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tudoumono/Sherpa/llms.txt

Use this file to discover all available pages before exploring further.

The graph endpoints expose Sherpa’s Neo4j knowledge graph for visualisation, exploration, and natural-language querying. The graph is partitioned by world — each version parameter selects a specific world’s graph partition. All graph endpoints require admin access. Nodes carry ontology type labels (e.g. Module, Copybook, DataItem, BusinessRule) and edges carry typed relationship labels (e.g. INVOKES, COPIES, CONTAINS).

​
GET /graph

GET /graph Return the full node and edge list for a world’s knowledge graph, formatted for graph visualisation. Admin only.

​
Query parameters

​
version
string
default:"v1"
World identifier. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

​
Response

​
world
string
World identifier (same as version).
​
version
string
World identifier (alias, for backward compatibility).
​
nodes
object[]
All graph nodes.
​
edges
object[]
All graph edges between nodes present in the response.
​
counts
object
Summary statistics: entities, entities_static, entities_llm, entities_both, relations, relations_static, relations_llm, relations_both, deprecated, hidden.
curl -s "http://localhost:8000/graph?version=payroll-2024" \
  -b "sherpa_session=<token>"

​
GET /graph/facets

GET /graph/facets Return the closed vocabulary of node labels, relationship types, and filterable attribute fields available in the graph. Use this to populate the search filters in the admin graph viewer. Admin only.

​
Response

The response shape is determined by graph_admin.facets() and contains the distinct values of node label types, relationship type labels, and attribute field names that appear in the graph across all worlds. 
curl -s http://localhost:8000/graph/facets \
  -b "sherpa_session=<token>"

​
GET /graph/search

GET /graph/search Search the knowledge graph by relationship type, node attribute value, or both. Returns matching nodes and edges in the same {nodes, edges} format as GET /graph. Admin only.

​
Query parameters

​
version
string
default:"v1"
World identifier.
​
relationship
string[]
Repeated query parameter. Filter to nodes connected by at least one of the specified relationship types. Values must be valid relationship labels from GET /graph/facets.
​
field
string
Node attribute field to filter on (e.g. status, extraction_method).
​
value
string
Value to compare the field against.
​
op
string
default:"eq"
Comparison operator for the attribute filter. eq is the only currently supported value.
​
include_deprecated
boolean
default:"false"
Include deprecated and hidden-candidate nodes in the results.
​
scope_paths
string[]
Restrict results to nodes within these subfolder prefixes.
​
limit
integer
default:"200"
Maximum number of nodes to return. Range: 1–1000.

​
Response

Same structure as GET /graph: {nodes, edges, counts}. 
curl -s "http://localhost:8000/graph/search?\
version=payroll-2024&\
relationship=INVOKES&\
relationship=COPIES&\
limit=100" \
  -b "sherpa_session=<token>"

​
POST /graph/ask

POST /graph/ask Ask a natural-language question about the knowledge graph. Sherpa uses the graph neighbour tool to find relevant nodes and returns them with context. This is a read-only path — no changes are made to the graph. Admin only.

​
Request body

​
question
string
required
A natural-language question about the knowledge graph (e.g. “Which modules depend on the TAXRATE copybook?”).
​
version
string
default:"v1"
World identifier to query.
​
scope_paths
string[]
default:"[]"
Restrict the graph traversal to nodes within these subfolder prefixes.

​
Response

The response shape is determined by graph_admin.ask_graph(). It includes matched nodes with their context and the reasoning used to answer the question.
This endpoint requires a configured LLM provider (set via PUT /settings). If no provider is configured, it returns 503.
curl -s -X POST http://localhost:8000/graph/ask \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "question": "Which modules call CALC-TAX directly?",
    "version": "payroll-2024",
    "scope_paths": ["src"]
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us