Command Palette

Search for a command to run...

Core API

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

Integration Sequencetext
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, 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

POST/chats pinned to a chapter

Pinning 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

POST /chats pinned to a chapterjson
{
  "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

POST/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.

POST /chats (Subject Chat)bash
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."
  }'
Subject Chat Response Examplejson
{
  "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"
  }
}
POST /chats (Global Chat)bash
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."
  }'
Global Chat Response Examplejson
{
  "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"
  }
}
POST/chats/{chatId}/messages

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.

POST /chats/{chatId}/messagesbash
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."
  }'
POST/chats/{chatId}/messages with an image

Send 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

POST /chats/{chatId}/messages with an imagebash
# 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"'"
      }
    ]
  }'
Attachment objectjson
{
  // 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"
}
POSTthen GET Flow

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.

POST then GET Flowbash
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>"
GET/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.

GET /chats/{chatId}bash
curl -X GET "https://{{domain}}/api/external/v1/chats/<chat_id>" \
  -H "Authorization: Bearer <your_api_key>"
Chats | Math AI Docs