Skip to main content
Chat endpoints power the interactive tutor that teaches subconcepts chunk-by-chunk with exercises and mastery tracking.

​
Sessions

​
List Sessions

curl "http://localhost:8000/api/chat/sessions?userId=00000000-0000-0000-0000-000000000000&nodeId=abc123"
GET /api/chat/sessions List chat sessions with optional filters.

​
Query Parameters

​
userId
string
Filter by user UUID
​
nodeId
string
Filter by node UUID

​
Response

​
[]
array
​
id
string
Session UUID
​
userId
string
User UUID
​
nodeId
string | null
Associated node UUID
​
startedAt
string
ISO 8601 timestamp
​
endedAt
string | null
ISO 8601 timestamp (null if active)

​
Create Session

curl -X POST http://localhost:8000/api/chat/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "nodeId": "abc123"
  }'
POST /api/chat/sessions Create a new chat session for learning a subconcept.

​
Body Parameters

​
userId
string
required
User UUID
​
nodeId
string
Subconcept node UUID
Status: 201 Created

​
End Session

PATCH /api/chat/sessions/:id End a chat session.

​
Body Parameters

​
endedAt
string
ISO 8601 timestamp (defaults to current time)

​
Messages

​
List Messages

GET /api/chat/sessions/:sessionId/messages Retrieve all messages in a session, ordered by creation time.
​
[]
array
​
id
string
Message UUID
​
sessionId
string
Session UUID
​
userId
string
User UUID
​
role
string
system, user, or assistant
​
kind
string
learning, hint_request, hint_response, or evaluation
​
content
string
Message content
​
wasSuccessful
boolean | null
Exercise success indicator
​
successSignal
string | null
JSON metadata about success
​
createdAt
string
ISO 8601 timestamp

​
Create Message

POST /api/chat/sessions/:sessionId/messages Manually create a message (rarely used - prefer the tutor endpoint).

​
Interactive Tutor

curl -X POST http://localhost:8000/api/chat/sessions/session123/tutor \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "content": ""
  }'
POST /api/chat/sessions/:sessionId/tutor Interactive tutoring - send student message, receive AI tutor response.

​
Flow

  1. Start: Send empty content to begin the session
  2. Teach: Tutor explains a chunk and asks a question
  3. Answer: Student responds with [ANSWER] prefix
  4. Evaluate: Tutor evaluates, gives feedback, moves to next chunk
  5. Complete: Session auto-ends when all chunks are covered

​
Body Parameters

​
userId
string
required
User UUID
​
content
string
required
Student message content:
  • Empty string: Start session
  • [ANSWER] ...: Answer to checkpoint question
  • [CLARIFICATION] ...: Request hint/clarification
​
drawingImageDataUrl
string
Data URL for drawing answer (for draw question type): data:image/png;base64,... or data:image/jpeg;base64,...

​
Response

​
message
string
Tutor’s response (includes explanation, question, and question type)
​
isComplete
boolean
Whether the subconcept is fully taught (session auto-ends if true)
​
toolsUsed
array
List of tools the tutor called (e.g., ["generate_example", "create_exercise"])
​
reasoning
array
Array of reasoning steps from the tutor agent

​
Tutor Tools

The tutor has access to these tools:
  • check_student_progress - Load diagnostic results for parent concept
  • check_prerequisite_mastery - Check if prerequisites are mastered
  • generate_example - Create a worked example
  • create_exercise - Create a practice problem
  • visualize_concept - Create an ASCII/text diagram
  • record_exercise_result - Persist exercise attempt + update mastery score

​
Hints

​
Create Hint Event

curl -X POST http://localhost:8000/api/chat/hints \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "nodeId": "abc123",
    "sessionId": "session123",
    "requestMessageId": "msg1",
    "responseMessageId": "msg2"
  }'
POST /api/chat/hints Record a hint request event.

​
Body Parameters

​
userId
string
required
User UUID
​
nodeId
string
required
Node UUID
​
sessionId
string
Session UUID
​
requestMessageId
string
Request message UUID
​
responseMessageId
string
Response message UUID
​
referencedSuccessMessageIds
array
Array of message UUIDs referenced in the hint

​
List Hints

GET /api/chat/hints?userId=USER_ID&nodeId=NODE_ID Retrieve hint events with optional filters.

​
Message Kinds

​
learning
kind
Normal tutoring exchange
​
hint_request
kind
Student requested clarification ([CLARIFICATION])
​
hint_response
kind
Tutor’s clarification response
​
evaluation
kind
Student’s answer to a checkpoint question ([ANSWER])

​
Question Types

The tutor can ask three types of questions:
​
text
question-type
Text-based answer expected
​
code
question-type
Code or pseudocode expected
​
draw
question-type
Drawing/diagram expected (submit via drawingImageDataUrl)

Build docs developers (and LLMs) love

Get started for freeTalk to us