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.

Every Sherpa user has a personal workspace — a private file area that lives at data/users/{uid}/workspace/files/ on the server. You can upload plain-text files (COBOL sources, Markdown notes, CSV exports, SQL scripts, and more), search them with a full-text grep, and delete them when no longer needed. Personal workspace files are completely isolated from the shared knowledge base: they are never indexed in Elasticsearch or Neo4j, never appear in other users’ search results, and are identified only by rel_path (never their physical path on disk). When personal: true is passed to the chat endpoint, grep hits from your workspace are merged into the answer sources under a distinct “personal files” label.

​
GET /workspace/files

GET /workspace/files List all files currently in the authenticated user’s personal workspace.

​
Response

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

​
POST /workspace/files

POST /workspace/files Upload a file to the authenticated user’s personal workspace. Uploading a file with the same name as an existing file overwrites it (upsert). The file is never indexed in the shared knowledge base.

​
Validation rules

  • Filename: must match ^[A-Za-z0-9][A-Za-z0-9._\-() ]{0,127}$ (path separators and control characters are rejected).
  • Extension: must be one of the allowed set (see below).
  • Size: must not exceed 10 MB (configurable via SHERPA_WORKSPACE_MAX_BYTES). Returns 413 if exceeded.

​
Allowed extensions

.txt .md .markdown .csv .tsv .json .yaml .yml .cbl .cob .cobol .cpy .copybook .jcl .sql .py .sh .bat
The allowed extension set is also the grep-search set. Every file you can upload can be searched. Binary files are not accepted.

​
Request

Multipart form upload with a single file field.

​
Response

​
ok
boolean
true on success.
​
id
integer
Ledger ID of the uploaded (or replaced) file.
​
rel_path
string
Stored filename.
​
size_bytes
integer
File size in bytes.
​
sha256
string
SHA-256 hex digest of the uploaded content.
curl -s -X POST http://localhost:8000/workspace/files \
  -b "sherpa_session=<token>" \
  -F "file=@TAXRATE.cpy"

​
DELETE /workspace/files/

DELETE /workspace/files/{file_id} Delete a file from the authenticated user’s personal workspace. Removes both the ledger record and the physical file. Only the file’s owner can delete it.

​
Path parameters

​
file_id
integer
required
Ledger ID of the file to delete (from GET /workspace/files or the POST /workspace/files response).

​
Response

​
ok
boolean
true on success.
​
id
integer
ID of the deleted file.
​
rel_path
string
Filename that was deleted.
curl -s -X DELETE http://localhost:8000/workspace/files/7 \
  -b "sherpa_session=<token>"

​
GET /workspace/search

GET /workspace/search Full-text grep across the authenticated user’s personal workspace files. The search is case-insensitive and scoped exclusively to files with status='uploaded' in the user’s own ledger — no shared knowledge base content is included. Results are capped at 50 hits. Each hit includes two lines of surrounding context.
Search results come from personal workspace files only. They are labelled "個人ファイル内ヒット" (personal file hits) to distinguish them from shared knowledge base citations.

​
Query parameters

​
q
string
required
Search string. Minimum length 1 character. Whitespace-only strings return 422. Matching is case-insensitive substring search.

​
Response

​
query
string
The trimmed search string that was executed.
​
source
string
Always "個人ファイル内ヒット" (personal file hits).
​
hits
object[]
Search results, up to 50 entries.
curl -s "http://localhost:8000/workspace/search?q=TAXRATE" \
  -b "sherpa_session=<token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us