AI Tutor

The AI Tutor allows learners to ask clarifying questions about specific lessons, request summaries, ask for quiz hints, or simplify complex topics.

Ask the AI Tutor

Submit a predefined prompt type or a custom question for a lesson. Predefined prompt responses are cached in Redis for 24 hours.

Endpoint

POST /api/v2/ai-tutor/ask

Headers

Authorization: Bearer <jwt_access_token>

Request Body

Field	Type	Required	Description
`lessonId`	`string`	Yes	UUID of the active lesson
`promptType`	`string`	Yes	`EXPLAIN`, `SUMMARIZE`, `QUIZ_HINT`, `SIMPLIFY`, or `CUSTOM`
`customQuestion`	`string`	No	Required if `promptType` is `CUSTOM` (max 500 characters)

{
  "lessonId": "9f1e8d7c-6b5a-4321-fedc-ba9876543210",
  "promptType": "EXPLAIN",
  "customQuestion": "Can you explain how gas fees work in this context?"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "requestId": "req-987213",
    "lessonId": "9f1e8d7c-6b5a-4321-fedc-ba9876543210",
    "promptType": "EXPLAIN",
    "answer": "Gas fees represent the computational effort required to execute operations on the blockchain...",
    "isCached": false,
    "remainingDailyQuota": 18
  },
  "message": "AI response returned successfully"
}

Submit AI Feedback

Rate an AI response (helpful vs not helpful) to improve model tuning.

Endpoint

POST /api/v2/ai-tutor/feedback

Request Body

Field	Type	Required	Description
`requestId`	`string`	Yes	ID from previous AI tutor response
`rating`	`number`	Yes	`1` for thumbs up, `-1` for thumbs down
`comment`	`string`	No	Optional user feedback comment

{
  "requestId": "req-987213",
  "rating": 1,
  "comment": "Very clear explanation!"
}

Response (200 OK)

{
  "success": true,
  "message": "Feedback recorded successfully"
}