OPENLESSON AGENT API SKILL

You are an AI agent that can interact with the openLesson tutoring platform via API.

OVERVIEW

openLesson is a tutoring system that uses audio-based dialogue to help users learn by asking questions rather than giving answers. The platform generates personalized learning plans as directed graphs, where each node is a session. Agents can programmatically generate learning plans, start sessions, and analyze audio chunks for reasoning gaps.

IMPORTANT: NO BROWSER TOOL REQUIRED

You do not need a browser tool. You only need shell tools (e.g., curl) to make API calls to openLesson.

IMPORTANT: AUDIO-ONLY SYSTEM

CRITICAL: The openLesson platform is audio-only. The analyze endpoint accepts ONLY audio input, NOT text.

Always convert speech to base64-encoded audio before calling the analyze endpoint
Supported formats: webm, mp4, ogg
Do not send text to the analyze endpoint — it will be rejected

AUTHENTICATION

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Important: Always use https://www.openlesson.academy for API calls. The domain openlesson.academy has a redirect that loses the Authorization header.

CREDENTIALS

This skill requires an API key for the openLesson API:

Environment variable: OPENLESSON_API_KEY
How to obtain: Generate from the user's dashboard at /dashboard

ENDPOINTS

1. GENERATE LEARNING PLAN

Creates a directed graph of learning sessions for a given topic.

Endpoint: POST /api/agent/plan

{
  "topic": "Machine Learning Fundamentals",
  "days": 30
}

Days to Sessions mapping:

7 days: 3-5 sessions
14 days: 4-7 sessions
30 days (default): 5-10 sessions
60 days: 8-14 sessions
90 days: 10-18 sessions
180 days: 15-25 sessions

2. START SESSION

Starts a new Socratic session.

Endpoint: POST /api/agent/session/start

{
  "problem": "Explain how gradient descent works in neural networks",
  "plan_node_id": "uuid-from-plan"
}

3. ANALYZE AUDIO CHUNK

Submits an audio chunk for Socratic analysis. Returns reasoning gap score and follow-up questions.

Endpoint: POST /api/agent/session/analyze

{
  "session_id": "uuid-from-start",
  "audio_base64": "base64-encoded-audio-data",
  "audio_format": "webm"
}

Response includes: gapScore, signals, transcript, followUpQuestion, requiresFollowUp

4. END SESSION

Ends an agent session and generates a summary report.

Endpoint: POST /api/agent/session/end

5. GET SESSION SUMMARY

Retrieves the summary report of a completed session.

Endpoint: GET /api/agent/session/summary?session_id=xxx

COMPLETE AGENT WORKFLOW

Generate a learning plan → get plan with nodes
Start a session for the first node → get session ID
Record and analyze audio → get gap scores and follow-up questions
Continue until concept mastery
End session → get summary report
Move to next node in the plan

TIPS FOR AGENTS

Always use audio: The analyze endpoint ONLY accepts audio
Record in webm format (Opus codec preferred)
Chunk audio: Send 30-60 second chunks for analysis
Follow up: If requiresFollowUp is true, ask the follow-up question
Track gap scores: Use gap score to determine mastery
Schedule all sessions: Create reminders for each planned session

ERROR HANDLING

401: Invalid or inactive API key
403: Session doesn't belong to this key
404: Session not found
500: Internal server error

open-lesson