Skip to main content
The Guide module creates interactive learning sessions from saved notebook records. A session walks through knowledge points one at a time, answers questions via chat, and can generate and fix interactive HTML exercises.

​
Endpoints

MethodPathDescription
POST/api/v1/guide/create_sessionCreate a new guided learning session
POST/api/v1/guide/startStart a session (get the first knowledge point)
POST/api/v1/guide/nextAdvance to the next knowledge point
POST/api/v1/guide/chatSend a chat message within a session
POST/api/v1/guide/fix_htmlFix a bug in the generated HTML exercise
GET/api/v1/guide/session/{session_id}Get session state
GET/api/v1/guide/session/{session_id}/htmlGet the current HTML exercise
WS/api/v1/guide/ws/{session_id}Real-time interaction via WebSocket
GET/api/v1/guide/healthHealth check

​
POST /api/v1/guide/create_session

Create a new guided learning session. You can provide either a single notebook ID or a list of records from multiple notebooks.

​
Request body

​
notebook_id
string
ID of a single notebook whose records will be used. Provide either this or records.
​
records
object[]
List of record objects for cross-notebook mode. Provide either this or notebook_id.

​
Response

​
session_id
string
Identifier for the new session. Required for all subsequent requests.
​
knowledge_points
string[]
Ordered list of knowledge points extracted from the notebook records.
​
total_points
number
Total number of knowledge points in the session.
curl -X POST http://localhost:8001/api/v1/guide/create_session \
  -H "Content-Type: application/json" \
  -d '{ "notebook_id": "nb_abc123" }'

{
  "session_id": "guide_xyz789",
  "knowledge_points": ["Backpropagation", "Gradient descent", "Activation functions"],
  "total_points": 3
}

​
POST /api/v1/guide/start

Start a session and retrieve the first knowledge point with its explanation and interactive exercise.

​
Request body

​
session_id
string
required
Session identifier.
curl -X POST http://localhost:8001/api/v1/guide/start \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "guide_xyz789" }'

​
POST /api/v1/guide/next

Advance to the next knowledge point in the session.

​
Request body

​
session_id
string
required
Session identifier.
​
learning_complete
boolean
true when all knowledge points have been covered.
curl -X POST http://localhost:8001/api/v1/guide/next \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "guide_xyz789" }'

​
POST /api/v1/guide/chat

Send a question or message within an active session. The guide agent answers in the context of the current knowledge point.

​
Request body

​
session_id
string
required
Session identifier.
​
message
string
required
The user’s message or question.
curl -X POST http://localhost:8001/api/v1/guide/chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "guide_xyz789",
    "message": "Can you give me an example of backpropagation on a simple network?"
  }'

​
POST /api/v1/guide/fix_html

Fix a bug in the interactive HTML exercise generated for the current knowledge point.

​
Request body

​
session_id
string
required
Session identifier.
​
bug_description
string
required
Description of the issue to fix.
curl -X POST http://localhost:8001/api/v1/guide/fix_html \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "guide_xyz789",
    "bug_description": "The submit button does not respond when clicked."
  }'

​
GET /api/v1/guide/session/{session_id}

Get the current state of a session, including progress and active knowledge point.
​
session_id
string
required
Session identifier.
curl http://localhost:8001/api/v1/guide/session/guide_xyz789
Returns 404 if the session is not found.

​
GET /api/v1/guide/session/{session_id}/html

Get the HTML content for the current knowledge point’s interactive exercise.
​
session_id
string
required
Session identifier.
curl http://localhost:8001/api/v1/guide/session/guide_xyz789/html

{ "html": "<!DOCTYPE html><html>...</html>" }
Returns 404 if the session is not found or no HTML has been generated yet.

​
WS /api/v1/guide/ws/{session_id}

WebSocket endpoint for real-time guided learning interaction. Use this instead of the individual REST endpoints when you need lower latency or a persistent connection.
​
session_id
string
required
An existing session ID created via POST /create_session.

​
Client messages

Send JSON objects with a type field:
typeAdditional fieldsDescription
start—Start learning (get first knowledge point)
next—Advance to the next knowledge point
chatmessage: stringSend a chat message
fix_htmlbug_description: stringRequest an HTML fix
get_session—Retrieve the current session state

​
Server messages

typePayloadDescription
task_idtask_id: stringSent on connection
session_infodata: objectSession state, sent on connection and in response to get_session
start_resultdata: objectResponse to start
next_resultdata: objectResponse to next
chat_resultdata: objectResponse to chat
fix_resultdata: objectResponse to fix_html
errorcontent: stringError message

​
Example

const ws = new WebSocket('ws://localhost:8001/api/v1/guide/ws/guide_xyz789');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'session_info') {
    console.log('Session loaded:', msg.data);

    // Start the session
    ws.send(JSON.stringify({ type: 'start' }));
  } else if (msg.type === 'start_result') {
    console.log('First knowledge point:', msg.data);
  } else if (msg.type === 'chat_result') {
    console.log('Guide answer:', msg.data);
  }
};

// Ask a question mid-session
function ask(question) {
  ws.send(JSON.stringify({ type: 'chat', message: question }));
}

Build docs developers (and LLMs) love

Get started for freeTalk to us