Chat, conversations, and troubleshoot API reference

The chat endpoints let you send messages to Sherpa and receive answers grounded in your registered document worlds. You can trigger retrieval-augmented generation by setting knowledge: true, narrow the search to specific subfolders with scope_paths, and optionally include your personal workspace files with personal: true. Conversation history is persisted automatically and can be listed, renamed, pinned, or deleted through the conversation management endpoints.

POST /chat

POST /chat Submit a message and receive a complete answer envelope synchronously. When knowledge is false (the default) the request is answered without consulting the knowledge base. Set knowledge: true to enable retrieval from the specified world.

Request body

message

string

required

The user’s question or statement.

version

string

default:"v1"

World identifier (the registered document folder). Must match the pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

conversation_id

integer | null

ID of an existing conversation to continue. Omit to start a new conversation. You cannot append to a received-share conversation (read-only).

knowledge

boolean

default:"false"

When true, Sherpa retrieves context from the world’s knowledge base (Elasticsearch + Neo4j) before answering. When false, the LLM answers from session context only.

scope_paths

string[]

default:"[]"

List of subfolder path prefixes within the world to restrict retrieval to. An empty list searches the entire world. Unknown or malformed paths return 422.

personal

boolean

default:"false"

When true, includes matches from the current user’s personal workspace files in the answer sources. Personal files are never indexed in the shared knowledge base.

Response

headline

string

The primary answer text.

lens

string

The reasoning lens used: impact, troubleshoot, or qa.

route

object

Routing decision metadata.

Show route fields

lens

string

The lens selected.

reason

string

Human-readable explanation of why this lens was chosen.

path

string[]

Display labels for the reasoning path.

scope

object

The scope that was actually searched.

Show scope fields

version

string

World ID used.

scope_paths

string[]

Normalised scope path list.

source

string

explicit when scope was supplied by the caller; all when the entire world was searched.

sources

object[]

Documents cited in the answer.

Show source fields

doc_id

string

Relative path of the source document within the world.

line

integer

Approximate line number of the cited passage.

conversation_id

integer

ID of the conversation this turn belongs to (new or existing).

personal_sources

object[]

Hits from the user’s personal workspace files, present only when personal: true produced results. Each entry includes rel_path, line, and text.

curl -s -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "message": "What does the CALC-TAX paragraph do?",
    "version": "v1",
    "knowledge": false
  }'

GET /chat/stream

GET /chat/stream Stream the thinking process and final answer as Server-Sent Events (SSE). This endpoint accepts the same parameters as POST /chat but as query-string arguments and returns text/event-stream.

Query parameters

message

string

required

The user’s question.

version

string

default:"v1"

World identifier.

conversation_id

integer

Existing conversation ID to continue.

knowledge

boolean

default:"false"

Enable knowledge base retrieval.

scope_paths

string[]

Repeated query parameter — e.g. ?scope_paths=src/tax&scope_paths=common.

personal

boolean

default:"false"

Include personal workspace grep results.

SSE event types

Each event is a JSON object delivered as data: <json>\n\n. The following type values are emitted:

`type`	Description
`node`	A thinking-step update. Contains `id`, `kind` (`think` or `tool`), `label`, `detail`, and `status` (`active` or `done`).
`answer_delta`	A streaming text chunk of the answer. Contains `text`.
`answer`	Final answer event. Contains `conversation_id` and `message` (full answer envelope).

The answer_delta events allow progressive rendering of the response. The final answer event always contains the complete envelope including sources and routing metadata.

curl -N "http://localhost:8000/chat/stream?\
message=What+calls+CALC-TAX&\
version=payroll-2024&\
knowledge=true&\
scope_paths=src/tax" \
  -b "sherpa_session=<token>"

GET /conversations

GET /conversations Return a list of all conversations owned by (or shared with) the current user.

Response

conversations

object[]

Array of conversation summaries. Each item includes id, title, created_at, updated_at, pinned, and origin (own or received_share).

curl -s http://localhost:8000/conversations \
  -b "sherpa_session=<token>"

GET /conversations/

GET /conversations/{cid} Retrieve a single conversation including its full message history.

Path parameters

cid

integer

required

Conversation ID.

Response

conversation

object

Conversation metadata: id, title, origin, pinned, created_at.

messages

object[]

Ordered list of turns. Each turn contains role (user or assistant), content, and created_at.

curl -s http://localhost:8000/conversations/42 \
  -b "sherpa_session=<token>"

DELETE /conversations/

DELETE /conversations/{cid} Delete a conversation. Both owned conversations and received-share wrapper conversations may be deleted.

Path parameters

cid

integer

required

Conversation ID to delete.

Response

boolean

true on success.

integer

ID of the deleted conversation.

curl -s -X DELETE http://localhost:8000/conversations/42 \
  -b "sherpa_session=<token>"

PATCH /conversations/

PATCH /conversations/{cid} Rename a conversation. Only the owning user can rename; received-share conversations return 403.

Path parameters

cid

integer

required

Conversation ID.

Request body

title

string

required

New title. Whitespace is trimmed; maximum 120 characters after trimming.

Response

boolean

true on success.

integer

Conversation ID.

title

string

The saved title (trimmed).

curl -s -X PATCH http://localhost:8000/conversations/42 \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"title": "CALC-TAX impact analysis"}'

POST /conversations//pin

POST /conversations/{cid}/pin Pin or unpin a conversation. Works for both owned conversations and received-share wrappers.

Path parameters

cid

integer

required

Conversation ID.

Request body

pinned

boolean

default:"true"

true to pin, false to unpin.

Response

boolean

true on success.

integer

Conversation ID.

pinned

boolean

The new pinned state.

curl -s -X POST http://localhost:8000/conversations/42/pin \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"pinned": true}'

POST /troubleshoot/run

POST /troubleshoot/run Run the troubleshoot lens directly for a given symptom description. This is a focused single-shot call that bypasses conversation history and returns a structured diagnostic answer grounded in the world’s knowledge base.

Request body

symptom

string

required

A description of the system behaviour or error to diagnose (e.g. “CALC-TAX returns wrong result for overtime employees”).

version

string

default:"v1"

World identifier (the registered document folder). Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

scope_paths

string[]

default:"[]"

List of subfolder path prefixes within the world to restrict retrieval to. Unknown or malformed paths return 422.

Response

The response shape is determined by lens_service.run_troubleshoot() and includes a diagnostic answer with supporting evidence from the knowledge base.

curl -s -X POST http://localhost:8000/troubleshoot/run \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "symptom": "CALC-TAX returns wrong value for overtime employees",
    "version": "payroll-2024",
    "scope_paths": ["src/tax"]
  }'

POST /qa/run

POST /qa/run Run the Q&A lens directly for a given question. This is a focused single-shot call that bypasses conversation history and returns a precise answer grounded in the world’s full-text index and knowledge base.

Request body

question

string

required

The question to answer from the world’s documents (e.g. “What is the purpose of the WS-TAX-RATE field?”).

version

string

default:"v1"

World identifier (the registered document folder). Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.

scope_paths

string[]

default:"[]"

List of subfolder path prefixes within the world to restrict retrieval to. Unknown or malformed paths return 422.

Response

The response shape is determined by lens_service.run_qa() and includes the answer with source citations from the knowledge base.

curl -s -X POST http://localhost:8000/qa/run \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "question": "What is the purpose of the WS-TAX-RATE field?",
    "version": "payroll-2024",
    "scope_paths": ["src/tax"]
  }'

Overview

Endpoints

Chat, conversations, and troubleshoot API reference

POST /chat

Request body

Response

GET /chat/stream

Query parameters

SSE event types

GET /conversations

Response

GET /conversations/

Path parameters

Response

DELETE /conversations/

Path parameters

Response

PATCH /conversations/

Path parameters

Request body

Response

POST /conversations//pin

Path parameters

Request body

Response

POST /troubleshoot/run

Request body

Response

POST /qa/run

Request body

Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /chat

​Request body

​Response

​GET /chat/stream

​Query parameters

​SSE event types

​GET /conversations

​Response

​GET /conversations/

​Path parameters

​Response

​DELETE /conversations/

​Path parameters

​Response

​PATCH /conversations/

​Path parameters

​Request body

​Response

​POST /conversations//pin

​Path parameters

​Request body

​Response

​POST /troubleshoot/run

​Request body

​Response

​POST /qa/run

​Request body

​Response

Build docs developers (and LLMs) love

POST /chat

Request body

Response

GET /chat/stream

Query parameters

SSE event types

GET /conversations

Response

GET /conversations/

Path parameters

Response

DELETE /conversations/

Path parameters

Response

PATCH /conversations/

Path parameters

Request body

Response

POST /conversations//pin

Path parameters

Request body

Response

POST /troubleshoot/run

Request body

Response

POST /qa/run

Request body

Response