Sherpa REST API: endpoints, base URL, auth, and error codes

Sherpa exposes a REST API built on FastAPI. Every feature available in the web UI — chat, impact analysis, document management, knowledge-graph queries, workspace file management, world registration, and administration — is accessible through this API. This page describes the base URL, authentication model, request/response conventions, and a complete table of every endpoint grouped by category.

Base URL

The API server binds to http://127.0.0.1:8000 by default. You can override the address with environment variables:

Variable	Default	Purpose
`SHERPA_HOST`	`127.0.0.1`	Bind host
`SHERPA_PORT`	`8000`	Bind port
`SHERPA_UVICORN_WORKERS`	`1`	Number of Uvicorn worker processes

http://<SHERPA_HOST>:<SHERPA_PORT>

Authentication

Sherpa supports two authentication modes, selected by the SHERPA_AUTH_ENABLED environment variable. Compatibility mode (default): When SHERPA_AUTH_ENABLED is not set, all requests are treated as coming from a synthetic admin user. No cookie is required. This mode is designed for local development and existing test pipelines. Auth mode: When SHERPA_AUTH_ENABLED=1, every protected endpoint requires a valid sherpa_session cookie issued by POST /auth/login. The cookie is HttpOnly, SameSite=Lax, and scoped to path=/. The Secure flag is set automatically in non-development environments (SHERPA_ENV not dev/development/unset).

Setting SHERPA_AUTH_DISABLED=1 forces compatibility mode regardless of other variables — useful when you need to override a deployment that has SHERPA_AUTH_ENABLED=1 set in its environment.

See Authentication for the full login/logout flow and curl examples.

Request and Response Conventions

JSON body — POST, PUT, and PATCH endpoints accept application/json.
Query parameters — GET endpoints use query parameters for filtering (e.g., version, scope_paths, q).
Multipart — POST /workspace/files accepts multipart/form-data for file uploads.
Streaming — GET /chat/stream returns text/event-stream (Server-Sent Events). Each event is a JSON object serialised as data: {...}\n\n.
File downloads — GET /documents/download and GET /impact/{aid}/export.xlsx return binary file responses.
All JSON responses use UTF-8 encoding. Timestamps are ISO 8601 strings.

The `version` Parameter

In Sherpa’s API, version is a world identifier — a slug that maps to a registered source directory (the “mirror” in Sherpa’s live-mirror model). The term version is kept for wire/database compatibility, but internally it always refers to a world_id. The default is v1.World IDs must match the pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. Providing an unregistered world ID returns 404. An ID with illegal characters returns 422.

Most endpoints that query or process documents accept version as either a query parameter or a body field. A handful of endpoints use a different parameter name — world for GET /documents/download and path variable {wid} for world-management routes. These exceptions are noted in the endpoint table below.

The `scope_paths` Parameter

Many endpoints accept scope_paths, a list of folder-prefix strings that narrow the search or analysis to a subfolder of the world. An empty list means the entire world. Providing a prefix that does not exist in the world returns 422.

Common Error Codes

Code	Meaning
`401`	Not logged in, or session expired. Log in again via `POST /auth/login`.
`403`	Insufficient permissions — e.g., a non-admin user accessing an admin-only endpoint, or accessing another user’s conversation.
`404`	World not found (unregistered `version`), resource not found (conversation, file, analysis, etc.), or original document not on disk.
`409`	Conflict — e.g., sharing a conversation that contains personal workspace files without `sanitize=true`; or registering a folder that is already bound to a different world ID.
`410`	Gone — legacy `/ingest/sources` endpoints are disabled by default (re-enable with `SHERPA_LEGACY_INGEST_SOURCES=1`).
`413`	File upload exceeds the limit set by `SHERPA_WORKSPACE_MAX_BYTES` (default 10 MB).
`422`	Validation error — invalid `scope_paths`, bad `uid` format, unsupported file extension, empty query string, or malformed request body.
`500`	Internal error. Common cause: an audit-log write failure. Sherpa is fail-closed — if an audit event cannot be written, the triggering action is rolled back and a 500 is returned.
`503`	Downstream unavailable — Neo4j, Elasticsearch, or the LLM provider did not respond.

Health Check

Use GET /healthz to check whether the API process is alive. It requires no authentication and returns {"ok": true} with HTTP 200. This is the correct target for load-balancer health probes and readiness checks.

GET /healthz

{"ok": true}

All Endpoints

The table below lists every endpoint. Auth required means the endpoint checks the session cookie (or requires admin role) when SHERPA_AUTH_ENABLED=1. In compatibility mode all endpoints are accessible without a cookie.

Auth

Method	Path	Auth required	Description
`POST`	`/auth/login`	None	Log in with username + password. Issues `sherpa_session` cookie on success.
`GET`	`/auth/me`	User	Return the current user’s uid, email, display name, and role.
`POST`	`/auth/logout`	User	Revoke the current session and clear the cookie.

Conversations & Shares

Method	Path	Auth required	Description
`GET`	`/conversations`	User	List all conversations owned by or shared with the current user.
`GET`	`/conversations/{cid}`	User	Get a single conversation with its messages.
`DELETE`	`/conversations/{cid}`	User	Delete a conversation (owner or received-share wrapper).
`PATCH`	`/conversations/{cid}`	User (owner)	Rename a conversation. Body: `{"title": "..."}`.
`POST`	`/conversations/{cid}/pin`	User (owner)	Pin or unpin a conversation. Body: `{"pinned": true}`.
`POST`	`/conversations/{cid}/shares`	User (owner)	Create a share link for a conversation. Returns a one-time URL.
`GET`	`/share/conversations/{token}`	User (invitee)	Redeem a share token. Redirects to the shared conversation or to login.
`POST`	`/conversation-shares/{share_id}/revoke`	User (owner)	Revoke an active share.

Workspace

Method	Path	Auth required	Description
`POST`	`/workspace/files`	User	Upload a file to the personal workspace (multipart). Max 10 MB; allowed extensions only.
`GET`	`/workspace/files`	User	List personal workspace files for the current user.
`DELETE`	`/workspace/files/{file_id}`	User	Delete a personal workspace file (logical + physical).
`GET`	`/workspace/search`	User	Full-text grep across personal workspace files. Query param: `q`.

Impact Analysis

Method	Path	Auth required	Description
`POST`	`/impact/run`	User	Run an impact analysis starting from a given node. Returns `analysis_id`. Body: `ImpactReq`.
`GET`	`/impact/{aid}`	User	Retrieve the full result of a previous impact analysis.
`GET`	`/impact/{aid}/export.xlsx`	User	Download the analysis result as an Excel workbook.

Chat

Method	Path	Auth required	Description
`POST`	`/chat`	User	Send a chat message. Supports knowledge-base lookup and personal file reference. Body: `ChatReq`.
`GET`	`/chat/stream`	User	Stream a chat response as Server-Sent Events. Query params mirror `ChatReq` fields.
`GET`	`/scopes`	User	Return the folder-scope tree for a world (used by the scope selector). Query: `version`.

Documents

Method	Path	Auth required	Description
`GET`	`/documents`	User	List all documents in a world’s ledger. Query: `version`. Physical paths are never exposed.
`GET`	`/documents/download`	User	Download the original source file for a document. Query: `world`, `rel` (relative path). Audit-logged; fail-closed on audit failure.

Worlds & Ingest

Method	Path	Auth required	Description
`GET`	`/versions`	User	List registered world IDs and labels (compatibility/selector helper).
`GET`	`/worlds`	Admin	List all registered worlds with their bound source paths.
`GET`	`/worlds/{wid}/status`	Admin	Get ingest status for a world: indexed doc count, graph node/edge count, ES chunk count.
`POST`	`/worlds`	Admin	Register a new source folder as a world and ingest it (idempotent — re-runs if already registered).
`POST`	`/worlds/diff`	Admin	Preview diff between a folder and the last ingested state (read-only, does not register).
`GET`	`/worlds/{wid}/diff`	Admin	Diff a registered world against its current folder contents (read-only).
`POST`	`/worlds/{wid}/extract`	Admin	Run LLM-based knowledge extraction and rebuild the graph for a world.
`POST`	`/worlds/{wid}/concepts/propose`	Admin	Ask the LLM to propose business-term ↔ code-item mappings (draft only, no graph change).
`POST`	`/worlds/{wid}/concepts/confirm`	Admin	Apply approved concept proposals to `concepts.json` and rebuild the graph.
`POST`	`/worlds/{wid}/concepts/disable`	Admin	Add a concept bridge to the denylist and rebuild the graph.
`POST`	`/worlds/{wid}/rebind`	Admin	Rebind a world to a new source folder (full delete + re-ingest).
`POST`	`/worlds/{wid}/refresh`	Admin	Re-ingest a world if the source folder has changed (change-detection).
`DELETE`	`/worlds/{wid}`	Admin	Permanently delete a world (wipes derived artefacts + registry entry). Fail-closed: audit must succeed first.
`POST`	`/ingest/rerun`	Admin	Force a full clean rebuild of a world. Body: `{"version": "..."}`.
`GET`	`/ingest/runs`	Admin	List ingest run history. Query: `version` (optional).
`GET`	`/ingest/preview`	Admin	Preview graph extraction content for a world (read-only).
`GET`	`/fs/list`	Admin	Browse server-side directories for world registration (limited to `SHERPA_BROWSE_ROOTS`).
`POST`	`/ingest/sources`	Admin	(Legacy, disabled by default) Register an ingest source.
`GET`	`/ingest/sources`	Admin	(Legacy, disabled by default) List ingest sources.
`POST`	`/ingest/sources/{source_id}/scan`	Admin	(Legacy, disabled by default) Scan an ingest source.
`POST`	`/ingest/sources/{source_id}/confirm`	Admin	(Legacy, disabled by default) Confirm and run an ingest source.

Graph

Method	Path	Auth required	Description
`GET`	`/graph`	Admin	Get knowledge graph visualisation data (nodes + edges) for a world. Query: `version`.
`GET`	`/graph/facets`	Admin	Return the closed vocabulary of node labels and relationship types for graph search.
`GET`	`/graph/search`	Admin	Search the graph by relationship type and/or attribute condition. Returns nodes + edges.
`POST`	`/graph/ask`	Admin	Answer a natural-language question using the knowledge graph (read-only).

Admin

Method	Path	Auth required	Description
`GET`	`/admin/users`	Admin	List all users.
`POST`	`/admin/users`	Admin	Create a new user. Body: `UserCreateReq`.
`PATCH`	`/admin/users/{uid}`	Admin	Update a user’s status, role, password, or display name. Body: `UserPatchReq`.
`GET`	`/admin/audit`	Admin	Query the audit log with filters. The query itself is also audit-logged (fail-closed).
`GET`	`/admin/audit/verify`	Admin	Verify the audit log hash-chain integrity. Returns `{"ok": true}` or `{"ok": false, "broken_at": ...}`.
`GET`	`/admin/es/search`	Admin	Full-text Elasticsearch search across a world’s index. Query: `version`, `query`, `scope_paths`, `k`.

Settings

Method	Path	Auth required	Description
`GET`	`/config`	User	Return the active LLM provider configuration for the current user.
`GET`	`/settings`	User	Return the current user’s settings (agent, models, API key presence, system prompt).
`PUT`	`/settings`	User	Update the current user’s settings. Body: `SettingsReq`.
`POST`	`/settings/test`	User	Test connectivity to a given LLM provider without saving anything. Body: `TestReq`.

Lens (Troubleshoot / Q&A)

Method	Path	Auth required	Description
`POST`	`/troubleshoot/run`	User	Run a troubleshooting analysis given a symptom description. Body: `TroubleshootReq`.
`POST`	`/qa/run`	User	Run a focused Q&A query against the knowledge base. Body: `QaReq`.

UI & Health

Method	Path	Auth required	Description
`GET`	`/healthz`	None	Health check. Returns `{"ok": true}`.
`GET`	`/`	None	Redirects to `/ui/chat.html`.
`GET`	`/ui/*`	—	Static web UI (served from `web/` directory).

Overview

Endpoints

Sherpa REST API: endpoints, base URL, auth, and error codes

Base URL

Authentication

Request and Response Conventions

The `version` Parameter

The `scope_paths` Parameter

Common Error Codes

Health Check

All Endpoints

Auth

Conversations & Shares

Workspace

Impact Analysis

Chat

Documents

Worlds & Ingest

Graph

Admin

Settings

Lens (Troubleshoot / Q&A)

UI & Health

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Base URL

​Authentication

​Request and Response Conventions

​The version Parameter

​The scope_paths Parameter

​Common Error Codes

​Health Check

​All Endpoints

​Auth

​Conversations & Shares

​Workspace

​Impact Analysis

​Chat

​Documents

​Worlds & Ingest

​Graph

​Admin

​Settings

​Lens (Troubleshoot / Q&A)

​UI & Health

Build docs developers (and LLMs) love

Base URL

Authentication

Request and Response Conventions

The `version` Parameter

The `scope_paths` Parameter

Common Error Codes

Health Check

All Endpoints

Auth

Conversations & Shares

Workspace

Impact Analysis

Chat

Documents

Worlds & Ingest

Graph

Admin

Settings

Lens (Troubleshoot / Q&A)

UI & Health