Chat API

POST /api/chat

Send a message to the live chatbot and receive a bot reply with real-time monitoring results.

Auth: Public (rate-limited by IP)

Rate Limit: 5/min, 40/day per IP address

Content-Type: application/json

Request Body:

Field	Type	Required	Description
sessionId	string	No	Existing chat session ID. Omit to create a new session
message	string	Yes	The customer's message text

Success Response (200):

{
  "sessionId": "clxxsession12345",
  "messages": [
    {
      "id": "clxxmsg1",
      "role": "user",
      "content": "What data plans do you offer?",
      "createdAt": "2026-04-08T12:00:00.000Z",
      "monitoringData": null
    },
    {
      "id": "clxxmsg2",
      "role": "assistant",
      "content": "We offer several data plans starting from...",
      "createdAt": "2026-04-08T12:00:01.000Z",
      "monitoringData": {
        "hallucination": {
          "isHallucinated": false,
          "reason": "Response is consistent with general knowledge"
        },
        "bias": {
          "score": 12,
          "reason": "No biased language detected"
        }
      }
    }
  ],
  "monitoringResult": {
    "hallucination": {
      "isHallucinated": false,
      "reason": "Response is consistent with general knowledge"
    },
    "bias": {
      "score": 12,
      "reason": "No biased language detected"
    }
  }
}

Error Responses:

Status	Body	Cause
400	{ "error": "Message is required" }	Missing message field
400	{ "error": "Chat session has ended" }	Session already completed
429	{ "error": "Rate limit exceeded" }	Rate limit hit
500	{ "error": "Failed to process chat" }	Server error

Notes:

• The bot reply is generated by Groq Llama (requires GROQ_API_KEY)
• Live monitoring runs automatically on each assistant reply
• monitoringResult contains the latest message's monitoring data
• monitoringData is stored per-message in the database (only on assistant messages)

---

GET /api/chat/[id]

Fetch a full chat session with all messages and monitoring data.

Auth: Public

URL Parameters:

Parameter	Type	Description
id	string	Chat session CUID

Success Response (200):

{
  "id": "clxxsession12345",
  "createdAt": "2026-04-08T12:00:00.000Z",
  "lastActivityAt": "2026-04-08T12:05:00.000Z",
  "endedAt": "2026-04-08T12:05:30.000Z",
  "endedReason": "user",
  "messages": [
    {
      "id": "clxxmsg1",
      "role": "user",
      "content": "What data plans do you offer?",
      "createdAt": "2026-04-08T12:00:00.000Z",
      "monitoringData": null
    },
    {
      "id": "clxxmsg2",
      "role": "assistant",
      "content": "We offer several data plans...",
      "createdAt": "2026-04-08T12:00:01.000Z",
      "monitoringData": {
        "hallucination": { "isHallucinated": false, "reason": "..." },
        "bias": { "score": 12, "reason": "..." }
      }
    }
  ]
}

Error Responses:

Status	Cause
404	Session not found

---

POST /api/chat/[id]/complete

End a chat session, trigger a full analysis, and send alert emails.

Auth: Public

Timeout: 120 seconds

URL Parameters:

Parameter	Type	Description
id	string	Chat session CUID

Request Body:

Field	Type	Required	Description
analysisMode	string	No	"gemini", "groq", or "both" (defaults to "gemini")
selectedAnalyses	string	No	Comma-separated analysis types (defaults to "hallucination,bias,toxicity")
violationDetails	object	No	If triggered by a violation: { "type": "hallucination" | "bias", "reason": "..." }

Success Response (200):

{
  "uploadId": "clxxupload12345",
  "success": true
}

Error Responses:

Status	Body	Cause
400	{ "error": "Session already completed" }	Session already ended
404	{ "error": "Session not found" }	Invalid session ID
500	{ "error": "..." }	Analysis or email failure

Notes:

• If violationDetails is provided, a "Live agent required" message is appended to the chat
• A full batch analysis runs on the entire conversation (hallucination + bias + toxicity)
• An Upload record is created with source: "chat" and appears in all analysts' upload history
• Alert emails are sent to all analysts who have configured an alertEmail in their settings
• The email includes violation details (if applicable), session ID, message count, and a link to the dashboard