API Reference: AI Assistant

This document details the RESTful API endpoints for the AI Assistant module, supporting RAG workflows.

---

1. Authentication

All requests MUST include a Platform JWT in the Authorization header.

Authorization: Bearer <JWT>

The JWT is issued by the Shell and contains the user's identity, organization, and roles.

---

2. Conversational Chat API

POST /sessions

Create a new chat session.

Response (201 Created):

{
  "data": {
    "id": "uuid",
    "title": "New Conversation"
  }
}

GET /sessions

List chat sessions for the current user.

POST /sessions/:id/messages

Send a message and receive a streaming (SSE) response.

Request Body:

{
  "content": "What is our company's remote work policy?"
}

Response (200 OK — SSE):

• event: message (delta tokens)
• event: sources (citations list)
• event: error (if failure)

GET /sessions/:id/messages

Fetch the message history for a session.

---

3. Knowledge Base API

GET /sources

List all indexed sources for the current organization.

POST /sources

Add a new source to the knowledge base (triggers indexing).

Request Body:

{
  "type": "url",
  "url": "https://handbook.example.com"
}

Or for Drive files:

{
  "type": "drive",
  "fileId": "uuid"
}

POST /sources/:id/sync

Manually trigger a re-index of an existing source.

DELETE /sources/:id

Remove a source and all its vector chunks from the knowledge base.

---

4. Feedback & Analytics API

POST /messages/:id/feedback

Rate an AI response.

Request Body:

{
  "isHelpful": true,
  "comment": "Very accurate answer!"
}

GET /analytics/summary

Get organization-wide usage stats (queries, active sessions, knowledge base health). Requires ADMIN role.

---

5. Standard Error Codes

Status Code	Description
400 Bad Request	Invalid query or source URL.
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	Insufficient permissions to manage knowledge base.
404 Not Found	Session or source does not exist.
429 Too Many Requests	Rate limit exceeded (e.g., token usage cap).
500 Server Error	LLM or Vector DB failure.