confluence/06-api-reference.md

06 · API Reference

All paths are relative; the React client (frontend/src/api.js) calls them. There is no admin-token auth (removed by design — the UI never prompts).

6.1 Turn & Feedback

Method	Path	Body / params	Notes
POST	/turn	{user_id, query, session_id?, generate_response?}	Path A; returns answer + classification + selection + timings
POST	/turn/stream	same	SSE: metadata → delta… → done
POST	/feedback	{response_id, user_id, signal, …}	Path B; appends a signal, may finalize reward
GET	/health	—	liveness

History is read server-side by session_id; clients don't send it. DB validation runs before writes, but unknown classifier intents do not stop the chat. Missing or inactive labels fall back to active unmapped and are stored as suggested_intent for admin review. /turn and /turn/stream return 422 only when the served intent has no active strategy candidates.

6.2 Config & Admin

• Read: /config/intents|strategies|policies|signal-rules|reward-scale|instructions|offers
• Write: POST /config/<entity>, POST /config/instructions/activate, POST /config/status (flip ACTIVE/INACTIVE/DRAFT)
• Delete: DELETE /config/<entity>/...
• Ops: /admin/seed, /admin/clear-user/{id}, /admin/clear-all, /admin/rebuild-bandit, /admin/db-snapshot, /admin/bandit-state, /admin/audit, /admin/rag-ingest

Strategy writes include format_type metadata only. The strategy remains the bandit arm; there is no nested format selection or alias-compliance layer.

6.3 Analytics (all support ?days=; many support ?domain=)

Path	Returns
/analytics/recompute	rebuild interest + trend_daily aggregates
/analytics/platform-overview	top topics, intent/signal mix, volume (domain-filterable)
/analytics/strategy-performance	per-format avg reward, tier, best/worst cell (domain-filterable)
/analytics/cognitive-facets	per-(intent,topic) cells (domain-filterable)
/analytics/active-users, /user-profile	per-user views (domain-filterable)
/analytics/trends, /topic(s)-timeseries, /platform-timeseries, /user-timeseries	trend charts (domain-filterable)
/analytics/customer-health	retention cohorts + satisfaction + segments
/analytics/rag-quality, /instruction-quality	failure hotspots by topic / instruction
/analytics/unmapped-intents	taxonomy backlog (domain-filterable)