Chalkmind API

Chalkmind rents out an AI teacher that teaches live on a board. While it talks, it writes, draws, points and erases, and every screen watching sees the same board at the same moment. There is one teacher, the AI with its teaching skill. Each customer (a tenant) makes its own teachers from it, for whatever it teaches: a school class, the stock market, spoken English, a company's product. Everything is done through this API, with the tenant's key.

The base address is https://HOST/v1. Every route also works without /v1. Bodies are JSON, and a request body is at most 1 MB; a book sent as a PDF may be up to 80 MB.

Keys: who may do what

Send the key as Authorization: Bearer cm_…. A key is shown once, when it is made; only its hash is kept.

• Channels. A key's channels say where it may teach: names (acme-10a) or prefixes (acme-*). A lesson runs on a channel, and the screens of that channel show it.
• Keys made from keys. A key makes keys only within its own rights: the same tenant, channels inside its own, and library rights only if it has them.
• The owner's first key comes from bin/keys.ts add --tenant owner --channels "*" --admin on the server. After that, everything goes through the API.

Quick start

KEY=cm_…   # a manage key of your tenant; your channels are acme-*

# 1. a teacher of your own
curl -X POST https://HOST/v1/teachers -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "id": "stock-market-basics", "name": "Stock Market Basics", "names": {"gu": "શેરબજારની પાયાની વાતો"},
  "subject": "the stock market and trading", "level": "adults who have never traded", "lang": "gu",
  "style": "Calm and practical: every idea with a chart and a small worked example in rupees.",
  "library": ["economics", "financial_markets", "share_types"]
}'

# 2. its book, chapter by chapter (or a whole PDF: Content-Type: application/pdf)
curl -X POST 'https://HOST/v1/teachers/stock-market-basics/book?lang=gu' -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"chapter": 1, "title": "શેર એટલે શું?", "text": "…"}'

# 3. a link for the students' screens (private lessons need one)
curl -X POST https://HOST/v1/tokens -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"channel": "acme-batch1", "minutes": 240}'
# → {"token": "v1.…", "display": "/board/acme-batch1/display?t=v1.…"}

# 4. the lesson: the board's own teacher teaches it, as your teacher
curl -X POST https://HOST/v1/board/acme-batch1/command -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"text": "Teach what a share is and how its price moves", "teacher": "stock-market-basics", "fresh": true}'

Then put the display link in your app:

<iframe src="https://HOST/board/acme-batch1/display?t=v1.…" allow="autoplay" style="aspect-ratio:100/64;width:100%;border:0"></iframe>

A Flutter app uses the liveboard_display package instead: BoardView(channelUrl: 'https://HOST/board/acme-batch1', token: 'v1.…').

Your own AI can teach instead of the board's: connect it to the MCP server (see MCP).

Teachers

A teacher is the AI made into the teacher of one subject. It is told who it is, whom it teaches and how, and it gets its book and its part of the library. Every lesson named for it is taught that way.

A teacher that is not a school class's is also told this: it teaches and does not advise. It never tells a learner what to buy, sell or take for their own money, health or legal matters, and it promises no results.

A teacher's "scope": "book" keeps it strictly to its book and the lesson's chapter; a question outside the book is never answered, gets one fixed line, and is flagged off_topic (see TEACHERS.md).

• Templates. A lesson may name a template as it is ("teacher": "std10-science"). A teacher made from one has that class's library, and its shared textbook until it has a book of its own.
• Your own library. Add stamps, diagrams, formulas and lesson patterns that only your lessons use (a candlestick chart, your lab's set-up): POST /library/items with a manage key, and DELETE /library/KIND/NAME to remove one. Each is drawn and checked first. In your lessons, searches and teachers, your names win over the shared ones. The item's form is in library/README.md.
• The library has 1,993 ready drawings: stamps, labelled diagrams, formulas and lesson patterns. They cover Std 10 to 12 in science, commerce and arts. GET /library lists the categories, and GET /library/search?q=WORD finds items.

Lessons

A lesson runs on a channel, and there is one lesson per channel at a time. All of these routes need a key for the channel.

• Learners. learner is your own student id, or a class's (class-10a). Without it, the learner is the class on the channel. The next lesson for the same learner starts from what the last one found.
• The teacher's memory. A lesson taught as a teacher (teacher) goes into that teacher's journal with the learner. Each lesson's next start tells the teacher four things:
  • how many lessons it has taught them;
  • the latest ones: when, what, with which pictures, how many questions, and how the class did;
  • what it taught more than once;
  • what the last lesson left out.

During the lesson, board_journal search=WORD finds when and how it taught something. Each teacher has its own journal and notes: the English teacher's lessons are not in the science teacher's memory.

• The year plan. The chapters in order come from your plan for the class, else your plan for every class of the teacher, else the order of the teacher's book. A chapter counts as taught when a lesson is that chapter: you say so when you start it ("chapter": 12), or the teacher reads it from its book. At the start of each lesson the teacher hears the plan, how far the class is, what is next, any chapter past its date, and what this lesson is.
• The class in the room. A student's screen says who it is: ?learner= (your id for the student) and ?name= (the name the teacher says).
  • Who is in class. The teacher hears who is in class at the start, and who joins or leaves after each step.
  • Answers by name. It hears who answered each question with what, so it praises right answers and corrects wrong ones by name.
  • Each student's record. At the start, and as students join, it hears how each has done in the class's lessons with it ("Ravi: 3 of the last 4 wrong; shaky: fractions"), those who need help first. It gives them a question they can get right, and never says a record aloud.
  • Questions by name. A student's question, typed or spoken, comes with the student's name, and the teacher answers them by name.
  • The record. All of it is kept: GET /lessons/:id/class for a lesson, and GET /learners/:id?history=1 for a student over all lessons.
• The class's length. "minutes": 40 on /session, /command or /teach (or the teacher's own minutes).
  • The time left. The teacher hears it after each step, and wraps up in the last 3 minutes (a recap and the close, nothing new). Your server hears lesson.ending then.
  • Content done early. It practises with the class instead of stopping.
  • A hard stop at the end. At its end the board stops the class: the teacher is stopped, what was already sent (at most the sentence being said) finishes on the screens, and the lesson ends (lesson.ended with "reason": "time"). Lines sent after it are refused (409), and a student's question after it starts no new lesson.
• Recording. A lesson is recorded when any of these holds: "record": true on /session, /command or /teach; a teacher with "record": true (unless the lesson says false); or the record button.
  • The video has the board and the voice, and only the parts recorded.
  • Videos are made one at a time after the lesson.
  • They are kept under recordings/TENANT/LESSON.mp4. Later they move to the R2 bucket, under the same key, and the API gives them from there.

A live class of the board's own teacher

What a class taught by the board's own teacher (/command) does with its students. Shikhar's app and the board's own buttons take the same path: POST /board/:ch/react?t=… and /board/:ch/doubt?t=… with who (the same id as the screen's ?learner=) and name.

• The voice never holds the class long. A sentence waits at most 8 s for its voice (the first seconds filled with a short phrase); then the board goes on with it as a caption, and the next sentences are spoken again.
• The board stays a few seconds ahead. It puts each sentence on the timeline shortly before it is due, so it can stop at the next sentence for a student. (GET /board/:ch/state has queued: lines written, not yet on.)
• A raised hand (kind: "hand"): at the next sentence the board says «હા Ravi, બોલો, શું પ્રશ્ન છે?» (or «હા, બોલો…» without a name), and waits 20 s for that student's question (half way, one reminder: «Ravi, તમારો પ્રશ્ન લખો કે બોલો, હું સાંભળું છું.»); every screen hears turn {who, name, until} and shows whose turn it is (chalk-turn on <chalk-board>; {who: null} when over). The question comes: «હા Ravi.», and the teacher answers it by name (no second greeting or praise), checks it with one MCQ, and goes on from where it stopped. None comes: «ઠીક છે Ravi, પછી પૂછજો.», the hand comes down, and that student's hand is off for 3 minutes. Several hands are taken in order.
• "Explain again" (kind: "again"), or a question saying the student did not understand: «હા Ravi, ચાલો ફરીથી સરળ રીતે સમજીએ.», then the teacher explains the last point again, more simply, by name, and checks it.
• A question at any time: the same, at the next sentence. One that says it was not understood ("khabar na padi", "samjayu nahi", "I did not get it") is taken as "explain again". One outside the book (scope: "book"): the fixed line with the student's name, and it is flagged. Gujarati or Hindi in Latin letters is understood as any question.
• "Understood" (kind: "got"): no interruption; the teacher hears how many.
• What the class may use. POST /board/:ch/controls {hand?, question?, again?} (a key for the channel; true or false) turns them on or off; the teacher can too (a controls hand=off line). While an MCQ is open all three are off. Every screen hears controls {hand, question, again} (chalk-controls) and greys the buttons; a call while one is off gets 409 {off}. While it is a student's turn, that student may ask even with questions off.
• MCQs. A screen's answer is POST /board/:ch/answer {ask, choice, who}, choice from 1 (1 is A); 0 is refused (400). The screens show the question's words with the choices (q). A student's screen gets the answer only when it closes (reveal {ask, answer, why}): right or wrong, the right answer, and, when the teacher gave it, why their own wrong choice is wrong. The teacher waits for the answers, then tells those who chose wrong, plainly and why.
• Points. A right answer earns 10 (or the MCQ's points, 20 in a revision round); the screen shows «સાચું! +10». GET /points?class=&learner=&lesson=&from=&to= gives each student's points, right and answered, most first; class.ended has the lesson's. What points are for is the host's choice.
• The end. When the lesson ends (its time, the host, or the Principal), nothing more is said; every screen shows «વર્ગ પૂરો થયો» (and «રેકોર્ડિંગ થોડી વારમાં તૈયાર થશે» when it was recorded) instead of the last page, with a button to watch it again; chalk-ended reaches the host's page.
• Each student, as they are. After each MCQ the teacher hears how each student does today against their earlier lessons, helps the one lower today first, and praises by name what improved (never a score aloud).
• Revision, not homework. The board's teacher sets no homework by itself. At the close it tells the class that what it learned will be asked at the start of the next class, for points; the next class with the same teacher starts with 3 to 5 MCQs on it, the shaky concepts first.

Screens

• Private lessons. On the hosted board every lesson is private: a screen shows it only with a token. Make tokens on your server, never in the students' app, since a token made in the app would need your key there.
• Answers. When the teacher asks the class a question (ask), the screens show the choices as buttons, and the answers come back to the teacher.
• Students' questions, typed or spoken.
  • Asking. Under the board, a student types a question, or taps the microphone and speaks it. The browser turns the speech into text in the lesson's language (Gujarati, Hindi or English). The teacher's voice goes quiet on that screen while the student speaks. Chrome, Edge and Safari can do this; a browser that cannot shows no microphone.
  • Who answers. The question waits on the channel until the teacher hears it.
    • The board's own teacher answers it at its next step while it teaches, or at once when it is free.
    • An AI that teaches over MCP gets it with its next board_write or board_status.
  • How it is answered. The teacher says whose question it is and answers it on the board: written, drawn and spoken. Then it checks the answer is understood.
  • What screens see. Each screen sees its own questions, waiting and then heard. Consoles see every question's words.
  • Limits. A screen may have 2 questions waiting, and a channel 20.

Your account

• The export. {format: "chalkmind-export/1", tenant, keys, users, hours, webhooks, teachers, books, library, learners, lessons}: your account, keys, users, hours and webhooks; your teachers and their books; your own library items; your learners and every note about them; and every lesson, with what was said and written, its pages, who took part and how, and its recording's url. It never holds a key, a password or a webhook's secret. Videos are fetched from their url.

Homework

The teacher sets homework at the end of a full lesson (or you set it): up to 10 questions. Each question is one of three kinds:

• choice: options, and the number of the right one.
• short: a word, a number or a sentence, with the expected answer.
• work: the working, typed or as a photo of the notebook, with the expected answer or its key steps.

Students answer on their screens, or through your app. Choices, and a short answer that is the expected one, are marked at once. The rest are marked by the AI, which reads the photo and writes one kind sentence on each question. Each student's marks become their notes, and the next lesson's teacher hears how the class did.

Tests. A test is homework with "kind": "test", in the pattern of the class's exam board:

• Questions. Up to 40. Each has its marks (1 to 10) and its section ("A").
• Timed or on paper. With minutes (5 to 240), it is written now, and answers are refused 5 minutes after the time is up. Without them, it is written on paper and handed in as up to 4 photos of the answer sheet (images), from the screen or your app. The AI reads every answer from the photos.
• Marking. Working and answers of more than a mark get step marks, as the board's examiner gives them.
• Paper. It prints as a paper (GET /homework/:id/paper, or the screen's link), and the teacher gets an answer key (?key=1).

Questions flagged for the school

A question is flagged when it is not about the lesson, is not kind, or is personal (about the teacher, or a student's private life). The teacher answers it with one kind sentence, goes on with the lesson, and flags it for you.

A student who may need help gets one warm sentence. That is a student who is very sad, hurt, unsafe or bullied, or speaks of harming themselves. The teacher tells them they are heard, and to talk to their parents or a teacher they trust today. It never discusses it before the class. The question is flagged concern, and your server hears it at once (question.flagged, urgent: true). An AI teaching over MCP flags with board_flag, or POST /board/:ch/flag {question, kind, note?}.

Reports

A class's days, or a student's, from the lessons, the homework and tests, and the teachers' notes. A report covers the last 7 days by default, or from and to (dates in India's time, at most 93 days). Its summary is in the lessons' language, or lang.

GET /flags, GET /reports/classes and the two report routes above take ?tenant=ID: another customer's flags and reports, for the owner's key (or admin login) only (403 for any other).

Every Sunday from 18:00 (India), each class taught that week has its report sent once to its tenant's server, with each student's (report.weekly).

Webhooks

Chalkmind tells your server when something happens, so it need not ask. These routes need a manage key.

• What a call is. A POST of {event, at, data} with the headers X-Chalkmind-Event, X-Chalkmind-Delivery and X-Chalkmind-Signature: sha256=<hex>. The signature is the HMAC-SHA256 of the body with the webhook's secret: check it before you believe the call.
• Retries. A call that fails is tried again after 10 s, 60 s and 5 minutes.
• Addresses. A webhook must be https, at a public address.

The Principal

The Principal watches every live class in the board server (every 5 s while a class is live) and takes safe steps when one goes wrong, one at a time, each kept with its reason (docs/SCHOOL.md §5, §6). It never deletes anything, changes keys or billing, restarts the server, or says more to the class than one fixed line.

An incident is {incident, kind, severity, lesson, channel, opened, closed?, outcome?, steps, snapshot}: kind is stalled, voice, dropped, hand or again; outcome is recovered, ended or gave_up; snapshot has counts only, never a student's words.

Logging in with Google

/login has "Sign in with Google" (GET /auth/google?next=/admin). Google sends the browser back to /auth/google/callback, where the board checks the one-time state and the ID token (issuer, this app, not expired, a verified email). An email named in LIVEBOARD_ADMIN_EMAILS comes in as the owner's admin (its user made if need be) and goes to /admin; anyone else only to an account that exists, at /account. The server's env needs GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and LIVEBOARD_ADMIN_EMAILS (deploy/env.example); the redirect URI set in Google's console is https://DOMAIN/auth/google/callback.

The owner

These routes need an owner key.

• Plans. A plan's minutesPerMonth are lesson minutes. When they are used up, a new lesson is answered 402.
• Pausing. active: false pauses a tenant, for example an unpaid plan: every call with its keys is answered 402 until it is active again.
• Deleting. The tenant's id is sent twice (?confirm=ID), because nothing comes back. Its live lessons are ended and their screens closed. Then everything of its own goes: its keys, users, hours, webhooks, teachers, books, library items, learners and their notes, and its lessons and their recordings. Keep its export first. An owner key cannot delete its own tenant, and a tenant whose keys are in the keys file (--keys) is refused (409) until they are taken out.

MCP

Any MCP client can teach on the board with the same key: Claude, claude.ai, Claude Code, or an agent platform.

• Hosted (Streamable HTTP): https://HOST/v1/mcp, with Authorization: Bearer KEY. Nothing needs to be installed. The first message is initialize, and the answer's Mcp-Session-Id goes with every later message.
• On your computer (stdio): node --experimental-transform-types bin/mcp.ts --board https://HOST --key KEY [--manage].

The tools:

• Teaching: board_teachers lists your teachers. board_start teacher=ID begins a lesson as one; its reply has the teacher's instructions and the students' link with a token. Then board_write, board_draw, board_look, board_book, board_library, board_state, board_status, board_hold, board_resume, board_remember, board_teach, board_command and board_end.
• With a manage key: teacher_save makes or changes a teacher, and teacher_book_add adds a chapter to its book.

The tools are described in MCP.md.

Errors and limits

Every error is {"error": "what is wrong"}.