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.

A Sherpa world is a registered document folder. When you register a folder, Sherpa scans its contents, builds a document ledger, and (if an LLM is configured) extracts a knowledge graph into Neo4j and indexes documents into Elasticsearch. All world management endpoints require admin access. Destructive operations (delete, rebind) are fail-closed: they write an audit event before executing and abort if the audit write fails.

​
GET /worlds

GET /worlds List all registered worlds. Admin only.

​
Response

​
worlds
object[]
Array of world records.
curl -s http://localhost:8000/worlds \
  -b "sherpa_session=<token>"

​
POST /worlds

POST /worlds Register a new folder as a world and trigger an initial ingest. If the folder is already registered, Sherpa checks for changes and re-ingests only if content has changed (idempotent). Admin only.
Windows paths (e.g. C:\projects\payroll) are automatically converted to their WSL /mnt/c/... equivalents. Symlink roots and paths that overlap the personal workspace directory are rejected.

​
Request body

​
path
string
required
Absolute path to the folder to register. May be a Windows path or a /mnt/... WSL path.
​
label
string
Display name for the world. Defaults to the folder’s base name.
​
world_id
string
Internal identifier. Auto-generated from the label if omitted. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

​
Response

​
ok
boolean
true on success.
​
action
string
"registered" for a new world, "reran" if the world existed and content changed, "unchanged" if the world existed and no changes were detected.
​
world
object
World metadata (world_id, label, root_path, storage_mode).
​
status
string
Ingest run status.
​
ledger
integer
Number of documents in the ledger after ingest.
​
changed
boolean
Whether content changed since the last ingest.
​
flags
string[]
Any warning flags emitted during ingest (e.g. unsupported file types).
​
summary
object
Ingest summary: graph_nodes, graph_edges, es_chunks, plus counts from the scan report.
curl -s -X POST http://localhost:8000/worlds \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "path": "/mnt/c/projects/payroll-2024",
    "label": "Payroll 2024"
  }'

​
GET /worlds//status

GET /worlds/{wid}/status Get the current ingest status and statistics for a world. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Response

​
ok
boolean
true if the world is accessible.
​
world_id
string
World identifier.
​
label
string
Display name.
​
root_path
string
Registered root directory path.
​
last_synced_at
string
ISO 8601 timestamp of the most recent successful sync, or null.
​
graph_nodes
integer
Number of nodes currently in the world’s knowledge graph.
​
graph_edges
integer
Number of edges currently in the world’s knowledge graph.
​
es_chunks
integer
Number of document chunks indexed in Elasticsearch.
curl -s http://localhost:8000/worlds/payroll-2024/status \
  -b "sherpa_session=<token>"

​
POST /worlds//refresh

POST /worlds/{wid}/refresh Re-ingest a world on demand. Sherpa compares the current folder contents to the last-known manifest and re-ingests only if changes are detected (change detection / live-mirror). Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Response

​
ok
boolean
true on success.
​
world_id
string
World identifier.
​
changed
boolean
Whether any documents changed during this refresh.
​
status
string
Ingest run status.
​
ledger
integer
Number of documents in the ledger after refresh.
​
flags
string[]
Warning flags emitted during ingest.
​
summary
object
Updated ingest summary (graph_nodes, graph_edges, es_chunks, etc.).
​
note
string
Human-readable outcome message.
curl -s -X POST http://localhost:8000/worlds/payroll-2024/refresh \
  -b "sherpa_session=<token>"

​
DELETE /worlds/

DELETE /worlds/{wid} Permanently delete a world — removes derived data (Neo4j graph partition, Elasticsearch index, derived Markdown copies) and the registry entry. The original source folder on disk is not touched. Admin only.
This operation is destructive and fail-closed. A world.delete_requested audit event is written before deletion begins; if the audit write fails the delete is aborted. If the Neo4j graph deletion fails, the registry row is preserved and 503 is returned.

​
Path parameters

​
wid
string
required
World identifier.

​
Response

​
ok
boolean
true on success.
​
world_id
string
The deleted world’s identifier.
curl -s -X DELETE http://localhost:8000/worlds/payroll-2024 \
  -b "sherpa_session=<token>"

​
POST /worlds//rebind

POST /worlds/{wid}/rebind Change the root directory of an existing world. The old world is completely deleted and rebuilt from the new path. Other worlds are unaffected. Admin only.
Rebind deletes all derived data for the world (graph, index, derived Markdown) and rebuilds from scratch. If the new ingest fails, the server attempts to restore the previous state.

​
Path parameters

​
wid
string
required
World identifier to rebind.

​
Request body

​
path
string
required
New absolute directory path (Windows or WSL format).
​
label
string
Optional new display label.

​
Response

​
ok
boolean
true on success.
​
world
object
Updated world metadata.
​
status
string
Ingest run status.
​
ledger
integer
Number of documents after ingest.
​
flags
string[]
Warning flags.
​
summary
object
Updated ingest summary.
​
note
string
Human-readable confirmation message.
curl -s -X POST http://localhost:8000/worlds/payroll-2024/rebind \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"path": "/mnt/d/archive/payroll-2024", "label": "Payroll 2024 (archive)"}'

​
POST /worlds/diff

POST /worlds/diff Compare a folder’s current contents against the last ingest manifest without making any changes. If the folder is not yet registered, all files appear as additions (useful for previewing a new registration). Read-only. Admin only.

​
Request body

​
path
string
required
Absolute path to the folder to compare (Windows or WSL format).

​
Response

Contains ok, registered (boolean), world_id (if registered), label, root_path, and diff counters (additions, deletions, modifications). 
curl -s -X POST http://localhost:8000/worlds/diff \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"path": "/mnt/c/projects/payroll-2024"}'

​
GET /worlds//diff

GET /worlds/{wid}/diff Show changes between the current folder contents and the last ingest for a registered world. Use this before triggering a refresh to understand what would change. Read-only. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Response

Contains ok, registered: true, world_id, label, root_path, and diff counters. 
curl -s http://localhost:8000/worlds/payroll-2024/diff \
  -b "sherpa_session=<token>"

​
POST /worlds//extract

POST /worlds/{wid}/extract Run LLM-based knowledge extraction on a world’s documents and rebuild the graph. Requires an LLM provider to be configured in settings. Uses a diff cache so re-running on unchanged documents is fast. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Request body

​
scope_paths
string[]
Restrict extraction to specific subfolder prefixes. Omit to extract the entire world.

​
Response

Returns ok, extraction status, graph_nodes, graph_edges, and a full summary object. 
curl -s -X POST http://localhost:8000/worlds/payroll-2024/extract \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"scope_paths": ["src/tax"]}'

​
POST /worlds//concepts/propose

POST /worlds/{wid}/concepts/propose Ask the AI to propose business-term ↔ code-item mappings (concept bridges) for human review. Only proposals backed by real DataItem nodes in the graph are returned. No graph changes are made until concepts are confirmed. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Request body

​
scope_paths
string[]
Restrict proposals to a specific subfolder. Omit for the entire world.

​
Response

Returns ok and a proposals list with suggested concept mappings awaiting human approval. 
curl -s -X POST http://localhost:8000/worlds/payroll-2024/concepts/propose \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{}'

​
POST /worlds//concepts/confirm

POST /worlds/{wid}/concepts/confirm Persist approved concept proposals to concepts.json and rebuild the graph to activate the concept bridges. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Request body

​
accepted
object[]
default:"[]"
The subset of proposals (from POST /worlds/{wid}/concepts/propose) that the reviewer has approved.

​
Response

Returns ok, the number of accepted concepts written, updated graph_nodes, graph_edges, and a full summary. 
curl -s -X POST http://localhost:8000/worlds/payroll-2024/concepts/confirm \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"accepted": [{"parameter": "Tax Rate", "realized_by": {"parent": "CALCTAX", "name": "WS-TAX-RATE"}}]}'

​
POST /worlds//concepts/disable

POST /worlds/{wid}/concepts/disable Add an incorrect auto-generated concept bridge to the deny list and rebuild the graph. Once disabled, the bridge will not reappear on future re-ingests. Admin only.

​
Path parameters

​
wid
string
required
World identifier.

​
Request body

​
parameter
string
required
The business-term label to disable (e.g. "消費税率").
​
realized_by
object
required
The code-item node to disassociate. Must contain parent (module/copybook name) and name (data item name).

​
Response

Returns ok, the disabled entry, updated graph_nodes, graph_edges, and a full summary. 
curl -s -X POST http://localhost:8000/worlds/payroll-2024/concepts/disable \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"parameter": "Tax Rate", "realized_by": {"parent": "CALCTAX", "name": "WS-WRONG-RATE"}}'

​
GET /ingest/runs

GET /ingest/runs List the ingest run history, optionally filtered by world. Admin only.

​
Query parameters

​
version
string
World identifier to filter by. Omit to list runs for all worlds.

​
Response

​
version
string | null
Filter applied, or null for all worlds.
​
runs
object[]
List of ingest run records. Each run includes world_id, status, created_at, ledger, and flags.
curl -s "http://localhost:8000/ingest/runs?version=payroll-2024" \
  -b "sherpa_session=<token>"

​
POST /ingest/rerun

POST /ingest/rerun Force a full clean rebuild of a world’s ledger and knowledge graph, ignoring the change-detection manifest. Use this to recover from a corrupted state. Admin only.

​
Request body

​
version
string
default:"v1"
World identifier to rebuild.

​
Response

​
version
string
World identifier.
​
status
string
Ingest run outcome.
​
ledger
integer
Number of documents after rebuild.
​
flags
string[]
Warning flags emitted during the run.
​
note
string
Confirmation message.
curl -s -X POST http://localhost:8000/ingest/rerun \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"version": "payroll-2024"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us