Chats
Create chats, continue conversations, and retrieve chat history for your users.
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}/messagesChat 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, lesson_id or section_id
Subject chat inherits global instructions automatically unless the subject excludes them
Global chat does not require subject lookup before creation
/chats pinned to a chapterPinning a Chat to a Chapter or Lesson
Optional, and the answer to the most common question we get: why can a student ask the tutor about a chapter they have not started? Because a subject-bound chat tells the tutor the course and nothing more. It never knew which chapter the student was on, so it had no way to tell ahead from behind.
Send the position and it does. Our column names predate the curriculum's vocabulary, so map carefully: your Course is our subject_id, your Chapter is our lesson_id, and your Lesson is our section_id. There is no equivalent of an Activity.
Send the deepest id you have and Math AI resolves everything above it, so lesson_id on its own is enough. If you send both lesson_id and subject_id they must agree, and the course that owns the id must be assigned to your API key, or the request is rejected.
Your Course -> subject_id (our subjects)
Your Chapter -> lesson_id (our lessons)
Your Lesson -> section_id (our sections)
All ids come from GET /curriculum
sequence_policy: open (default) lets the tutor pitch answers to the chapter without withholding anything
sequence_policy: focus keeps the student on the current chapter; earlier chapters and general maths questions stay fully open
focus is guidance, not a lock -- the model knows maths independently of your curriculum, so a student can still get a general answer
The policy is stored on the conversation, so every later message inherits it; start a new chat to change it
{
"lesson_id": "<chapter id from GET /curriculum>",
"external_user_id": "student-123",
"sequence_policy": "focus",
"message": "What are we covering in this chapter?"
}If Material Must Be Withheld
Read this before designing around a lock. Gating controls access to the tutor, not access to knowledge. A student sitting in chapter 3's chat can ask a chapter 9 question and get a correct general answer, because the model knows mathematics whether or not your curriculum has introduced it. No setting on either side changes that, and a design that assumes otherwise will fail quietly.
If all you need is "do not teach ahead in this conversation", sequence_policy: focus already does it and nothing more is required. If you need "this student may not use the tutor for this chapter at all", that is yours to enforce — you hold enrolment and progress, and Math AI never sees either.
Do not render the chat on a locked page — the only true gate
Control which id you send: the conversation is pinned at creation and a student cannot move it
Check entitlement in your backend before calling us; never let a browser choose the lesson_id
To make a whole course unreachable, ask us to unassign it from your API key — every id beneath it then returns Subject not available or access denied
Remember your global 'Ask AI' entry point: it has no chapter pinned, so gating chapter chats while leaving it open gates nothing
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
/chats (Subject Chat)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.
For a chat opened from a chapter or lesson page, send lesson_id or section_id instead of subject_id and the tutor will know where the student is — see Pinning a Chat to a Chapter or Lesson below.
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"
}
}/chats/{chatId}/messagesSend 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."
}'/chats/{chatId}/messages with an imageSend An Image With A Message
Add an optional attachments array to send a photo of a handwritten problem, a textbook page, or a diagram. The tutor reads the image and answers about it, using the same bound curriculum instructions as a text-only question.
Images are sent as base64 data URLs rather than links. We deliberately do not fetch a URL on your behalf: doing so would let any caller point our servers at addresses only our network can reach, so accepting the bytes directly keeps that door shut. Encode the file you already hold and send it.
Attachments are stored with the chat and returned with message history, so later turns keep their context. Everything here is optional — existing integrations are unaffected.
Up to 4 images per message, 10MB each after decoding
Accepted types: image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif
Resize before sending: the model works at roughly 1568px on the long edge, so larger uploads cost bandwidth and buy nothing
A rejected attachment returns 400 with code INVALID_ATTACHMENT and a message naming the index
# base64 the image first (no line wrapping)
IMG=$(base64 -w 0 problem.jpg)
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-003" \
-d '{
"message": "Can you check my working in this photo?",
"attachments": [
{
"name": "problem.jpg",
"data": "data:image/jpeg;base64,'"$IMG"'"
}
]
}'{
// required: a base64 data URL, including the mime prefix
"data": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
// optional: shown in history; defaults to attachment-1.jpg
"name": "problem.jpg"
}then GET FlowContinue 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>"/chats/{chatId}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>"