Chats

Complete Chat Flow

The external chat API now supports two practical chat modes. If your request includes subject_id, Math AI creates a subject-bound chat. If subject_id is omitted, Math AI creates a global chat for general math support.

Instruction scope is resolved internally by Math AI. During normal chat usage, tenant developers do not need to send a separate instruction scope parameter. Subject chat anchors the learning context to one subject, while global chat uses only the global instruction layer.

• Use GET /subjects or GET /curriculum when you need an assigned subject_id for a subject chat

• Use POST /chats with subject_id for a subject-bound conversation

• Use POST /chats without subject_id for a global/general math conversation

• Save chat_id on your side for later continuation or history views

• Use POST /chats/{chatId}/messages for every follow-up message

• Use GET /chats/{chatId} to read the full stored conversation history

Subject chat:
1. GET /subjects
2. Choose subject_id returned for the tenant
3. POST /chats with subject_id
4. Save data.chat_id in your own system
5. POST /chats/{chatId}/messages

Global chat:
1. POST /chats without subject_id
2. Save data.chat_id in your own system
3. POST /chats/{chatId}/messages

Chat Scope Rule

• If subject_id exists, Math AI creates a subject chat

• If subject_id is missing, Math AI creates a global chat

• course_id is only valid together with subject_id

• Subject chat inherits global instructions automatically unless the subject excludes them

• Global chat does not require subject lookup before creation

Language Behavior

You can send language on both chat creation and follow-up message calls. Supported codes are en, my (or mm), no, and bn.

For best consistency, choose the intended language when creating a new chat and keep the same language within the same thread. Switching language inside a long existing conversation can work, but older history can still influence the next reply because the model sees the prior messages.

• Create a new chat when you want the cleanest language switch

• Send language again on follow-up messages if you want to override the next reply

• A GET /chats response always shows the full history, so older messages stay in their original language

• Use a new Idempotency-Key for every intentional new POST request

Create a Chat

Create a subject chat by including subject_id, or create a global chat by omitting subject_id. Save the returned chat_id on your side for later continuation.

If you want the AI response in a specific language, send language in the request body. Supported codes are en, my (or mm), no, and bn.

curl -X POST "https://{{domain}}/api/external/v1/chats" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-chat-001" \
  -d '{
    "subject_id": "<subject_id>",
    "external_user_id": "user-123",
    "language": "en",
    "message": "Explain equivalent fractions."
  }'

{
  "success": true,
  "request_id": "request-123",
  "data": {
    "chat_id": "chat-123",
    "scope": "subject",
    "subject_id": "<subject_id>",
    "message": "Chat created and AI response generated successfully",
    "next_steps": [
      "Use POST /api/external/v1/chats/{chat_id}/messages to send more messages",
      "Use GET /api/external/v1/chats/{chat_id} to get chat history"
    ]
  },
  "tenant": {
    "id": "tenant-123",
    "name": "Example Tenant"
  }
}

curl -X POST "https://{{domain}}/api/external/v1/chats" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-chat-global-001" \
  -d '{
    "external_user_id": "user-123",
    "language": "en",
    "message": "Help me study math today."
  }'

{
  "success": true,
  "request_id": "request-456",
  "data": {
    "chat_id": "chat-456",
    "scope": "global",
    "subject_id": null,
    "message": "Chat created and AI response generated successfully",
    "next_steps": [
      "Use POST /api/external/v1/chats/{chat_id}/messages to send more messages",
      "Use GET /api/external/v1/chats/{chat_id} to get chat history"
    ]
  },
  "tenant": {
    "id": "tenant-123",
    "name": "Example Tenant"
  }
}

Send the Next Message

Use the canonical messages path for follow-up messages. The legacy POST /chats/{id} path remains supported for compatibility.

You can include language again on follow-up messages to override the response language. If omitted, Math AI reuses the language saved when the chat was created when available.

curl -X POST "https://{{domain}}/api/external/v1/chats/<chat_id>/messages" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: message-001" \
  -d '{
    "language": "en",
    "message": "Now give me one example."
  }'

Continue Chat And Read History

After creating the chat, tenant backends should keep the returned chat_id and reuse it for future messages from the same user/session. This is the normal continuation flow for LMS or partner portal integrations.

curl -X POST "https://{{domain}}/api/external/v1/chats/<chat_id>/messages" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: message-002" \
  -d '{
    "message": "Now give me one more example.",
    "language": "en"
  }'

curl -X GET "https://{{domain}}/api/external/v1/chats/<chat_id>" \
  -H "Authorization: Bearer <your_api_key>"

Read Chat History

This endpoint returns the full stored conversation, not only the newest reply. When checking language behavior, always inspect the latest assistant message rather than assuming older history should change retroactively.

curl -X GET "https://{{domain}}/api/external/v1/chats/<chat_id>" \
  -H "Authorization: Bearer <your_api_key>"