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 documents endpoints expose the mirror-model document ledger — a live scan of a registered world’s folder tree. Each document is identified by its world-root-relative path (doc_id); physical paths on disk are never returned. You can browse scoped folder prefixes for use in chat and impact queries, download original source files (Office documents, COBOL sources, Markdown) for citation, and preview a world’s document set before or after ingest.

​
GET /documents

GET /documents Return the document ledger for a world. Documents are derived from a live folder scan; the list always reflects the current state of the registered directory.

​
Query parameters

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

​
Response

​
version
string
The world ID the ledger was generated for.
​
documents
object[]
Array of document records. Physical paths are not included.
curl -s "http://localhost:8000/documents?version=payroll-2024" \
  -b "sherpa_session=<token>"

​
GET /documents/download

GET /documents/download Download the original source file for a document in a world. This is the citation download endpoint — it serves the raw binary (.xlsx, .docx, .cbl, .md, etc.) as a file attachment. The path is resolved against the world’s registered root directory; path traversal attempts return 404. This action is recorded in the audit log.
This endpoint is fail-closed on audit: if the audit log write fails, the download is blocked and a 500 is returned. This ensures every document download has an audit trail.

​
Query parameters

​
world
string
default:"v1"
required
World identifier. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
​
rel
string
required
World-root-relative path of the document to download (the name / doc_id field from the ledger). The path must be within the world’s registered root directory.

​
Response

Binary file content with Content-Disposition: attachment; filename="<filename>". The MIME type is determined by the file extension. 
curl -s -OJ \
  "http://localhost:8000/documents/download?world=payroll-2024&rel=src/tax/CALCTAX.cbl" \
  -b "sherpa_session=<token>"

​
GET /scopes

GET /scopes Return the available scope paths (subfolder prefixes with document counts) for a world. Use this endpoint to populate the scope selector in the UI or to enumerate valid values for the scope_paths field in chat, impact, and graph requests.

​
Query parameters

​
version
string
default:"v1"
World identifier.

​
Response

A scope tree object. The exact shape is determined by scope.scope_tree() — each entry in the tree includes the folder prefix and a document count. 
curl -s "http://localhost:8000/scopes?version=payroll-2024" \
  -b "sherpa_session=<token>"

​
GET /ingest/preview

GET /ingest/preview Preview the documents and extracted knowledge for a world without triggering a new ingest run. Returns the extraction state — entities, relations, and document list — as currently stored in the derived data. Admin only.

​
Query parameters

​
version
string
default:"v1"
World identifier.

​
Response

​
world
string
World ID.
​
counts
object
Summary counts: entities, entities_static, entities_llm, entities_both, relations, relations_static, relations_llm, relations_both, deprecated, hidden.
​
documents
object[]
Preview document list. Each entry has name, doctype, branch, top_scope, phase, category, folder, state, label, and reason.
curl -s "http://localhost:8000/ingest/preview?version=payroll-2024" \
  -b "sherpa_session=<token>"

​
GET /versions

GET /versions List all registered worlds and their display labels. This is a backwards-compatibility endpoint; the canonical world management API is GET /worlds.
The UI’s world selector uses GET /worlds. Use GET /versions only if you need a lightweight name→label map for an existing integration.

​
Response

​
versions
string[]
Array of world identifiers.
​
labels
object
Map of world_id → display label string.
curl -s http://localhost:8000/versions \
  -b "sherpa_session=<token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us