API and Event Contracts

API and Event Contracts

API Surface Overview

flowchart LR
  U["Client services"] --> A["AI endpoints"]
  U --> C["Chat endpoints"]
  U --> S["Session start endpoint"]
  U --> W["Canvas endpoints"]
  U --> M["Maps endpoints"]
  U --> D["Dashboard endpoints"]
  A --> X["Scope and metadata normalization"]
  C --> Y["Thread scope validation"]
  S --> Y
  W --> Z["Workspace orchestration"]

0) Session Start Contract (/api/sessions/start)

ใช้สำหรับ flow เริ่มแชตใหม่จากหน้า chat/discovery เพื่อให้ได้ thread+scope ที่ canonical ก่อนเริ่มส่งข้อความ

Request (หลัก)

• projectId
• agentId
• scopeId (optional)
• history (workspace หรือ all)
• intent (new)
• source (trace source)

Response (หลัก)

• threadId
• scopeKind (general|board|map|dashboard)
• scopeId (nullable ตามโหมด)
• canonicalPath
• sessionVersion
• meta.threadCreated, meta.scopeCreated

1) AI Contract (/api/ai/*)

Required Context Keys (ตาม flow)

• threadId
• agentType
• projectId (resolve/inject ตาม implementation)
• scope keys ที่เกี่ยวข้อง (boardId หรือ mapId หรือ dashboardId)
• shareSessionId (เมื่อเป็น shared flow)

Metadata ที่ใช้จริง (ตัวอย่าง)

• knowledge_search
• attached_file_ids
• canvas_framework
• dashboard_context

Event Shapes ที่ UI ต้องรองรับ

• chunk
• interim
• done
• search_results
• action/hitl payload ที่ผ่าน normalization แล้ว

2) Chat Contract (/api/chat/*)

Endpoint	Responsibility	Contract rule
POST /api/chat/threads	create thread	enforce scope semantics ต่อโหมด
GET/POST /api/chat/messages	read/write messages	reject เมื่อ thread-scope mismatch
GET /api/chat/history	thread/workspace history	รองรับ scoped lookup และ append workspace name

3) Workspace Contracts

Domain	Endpoints	Scope canonical
Canvas	/api/canvas/workspace, /api/canvas/ops, /api/canvas/context	boardId
Maps	`/api/maps/workspace	ops
Analytics	/api/dashboard/*, /api/dashboard/context	dashboardId

4) Resume Contract

sequenceDiagram
  participant UI as useChatActions
  participant BFF as AI resume API
  participant ENG as AI engine

  UI->>BFF: resume with thread and decisions
  BFF->>BFF: validate scope and normalize payload
  BFF->>ENG: forward continuation request
  ENG-->>BFF: continuation response
  BFF-->>UI: normalized continuation events

5) Error Semantics (ต้อง deterministic)

• 400: payload/schema ไม่ผ่าน หรือ scope key ไม่ครบ
• 403: ไม่มีสิทธิ์ใน project/thread/scope นั้น
• 404: thread/scope ไม่พบ หรือไม่ตรงกับ context ปัจจุบัน
• 503: schema/runtime dependency ยังไม่พร้อม (เช่น map_scope_schema_outdated)

6) Contract Governance

1. เพิ่ม field ใหม่ใน /api/ai/* ต้องผ่าน allowlist ก่อนเสมอ
2. ห้ามใช้ scope key หลายแบบปนกันใน endpoint ที่ต้อง canonical เดียว
3. UI ต้องไม่ assume event shape เดียว ควรรองรับ fallback parser
4. New chat path ควรเรียก /api/sessions/start ก่อนส่งข้อความทุกครั้งที่ไม่มี thread