API contract

Interactive docs (Swagger): api.cae-copilot.dmitryivanov.dev/docs

POST /ask

Synchronous graph invocation. Returns the full response when complete.

Request:

{
  "user_query": "What coupling modes does Rocky support with ANSYS Fluent?",
  "request_id": "optional-correlation-id",
  "mode": "deep"
}

Field	Type	Default	Description
user_query	string	required	User question (1–4000 chars)
request_id	string	auto UUID	Correlation id for logs and feedback
mode	"quick" | "deep"	"deep"	Quick skips RAG for doc intents; Deep runs full retrieval

Response:

{
  "request_id": "...",
  "intent": "knowledge",
  "final_answer": "...",
  "source_notice": "...",
  "citations": [],
  "citation_cards": [],
  "follow_up_questions": [
    "What are the limitations of particle heat transfer?",
    "How does convection differ from conduction here?"
  ],
  "metadata": {
    "confidence": 0.82,
    "confidence_percent": 82,
    "sources_used": 2,
    "retrieved_chunks": 5,
    "response_time_ms": 1200.5,
    "intent_confidence": 0.95
  },
  "tool_results": [],
  "trace": []
}

follow_up_questions — 0–3 short contextual prompts the UI may show as clickable chips above the chat input (LLM-generated when configured, otherwise rule-based fallback from intent and citations).

POST /ask/stream

Server-Sent Events (text/event-stream) for pipeline stages, LLM tokens, and a final payload.

Request body is the same as POST /ask.

Event types (each line is data: {json}\n\n):

event	Fields	Description
stage	node, status, optional retrieved	Pipeline progress (intent, rag, tools, report; start or done)
token	text	Incremental LLM token from report synthesis
final	data	Full AskResponse object (same shape as /ask)
error	detail	Stream failure message

Example client loop:

for line in response.iter_lines():
    if line.startswith("data: "):
        payload = json.loads(line[6:])
        if payload["event"] == "token":
            print(payload["text"], end="")

POST /feedback

Lightweight thumbs up/down (logged only, no database).

{
  "request_id": "uuid-from-ask",
  "query": "original question",
  "rating": "up"
}

Returns {"status": "ok"}.

GET /suggest-questions

Returns clickable starter questions when the user clicks Not sure what to ask? in the UI.

Param	Type	Default	Description
count	int	5	Number of questions (1–8)

Response:

{
  "questions": [
    "How do I set up one-way CFD coupling?",
    "What particle shapes does Rocky support?"
  ]
}

Other routes

• GET /health — service status
• GET /legal — disclaimer, source notice, rights contact
• GET /tools — registered engineering tool names
• GET /kb/stats — knowledge-base statistics
• GET /architecture — RAG pipeline layer diagram data
• GET /suggest-questions?count=5 — random exploration prompts for the empty-state UI (1–8 questions; LLM when configured, otherwise rule-based fallback)