Interact with the openLesson tutoring API to generate learning plans, start audio-based sessions, analyze reasoning gaps, and manage tutoring workflows.
# 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.
API keys can be generated from the user's dashboard at `/dashboard`.
## 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`
- **No calendar access needed**: The skill does NOT create actual calendar events. "Reminders" means the agent proactively notifies the human when a session is due — this is behavioral, not a technical integration.
## Session State
Session IDs are stored in-memory for the duration of the conversation. No persistent storage is used or required.
## Bash Command Patterns
When running API calls as shell commands, use this pattern to avoid JSON escaping issues:
### Basic POST with JSON body
```bash
bash -c 'printf "{\"topic\":\"Quantum Computing\",\"days\":60}" | curl -X POST "https://www.openlesson.academy/api/agent/plan" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-'
```
### With variables
```bash
TOPIC="Quantum Computing"
DAYS=60
bash -c "printf '{\"topic\":\"$TOPIC\",\"days\":$DAYS}' | curl -X POST 'https://www.openlesson.academy/api/agent/plan' -H 'Authorization: Bearer $OPENLESSON_API_KEY' -H 'Content-Type: application/json' --data-binary @-"
```
### Start session
```bash
bash -c 'printf "{\"plan_node_id\":\"NODE_UUID\",\"problem\":\"Explain neural networks\"}" | curl -X POST "https://www.openlesson.academy/api/agent/session/start" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-'
```
### Analyze audio
```bash
bash -c 'printf "{\"session_id\":\"SESSION_UUID\",\"audio_base64\":\"BASE64_DATA\",\"audio_format\":\"webm\"}" | curl -X POST "https://www.openlesson.academy/api/agent/session/analyze" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-'
```
## Endpoints
### 1. Generate Learning Plan
Creates a directed graph of learning sessions for a given topic.
**Endpoint**: `POST /api/agent/plan`
**Request**:
```json
{
"topic": "Machine Learning Fundamentals",
"days": 30 // optional: number of days to spread the plan across (default: 30)
}
```
**Response**:
```json
{
"planId": "uuid",
"topic": "Machine Learning Fundamentals",
"days": 30,
"nodes": [
{
"id": "uuid",
"title": "Introduction to ML",
"description": "Basic concepts and overview",
"is_start": true,
"next_node_ids": ["uuid2"],
"status": "available"
}
]
}
```
**Days to Sessions**:
- 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`
**Request**:
```json
{
"problem": "Explain how gradient descent works in neural networks",
"plan_node_id": "uuid-from-plan" // optional, links to plan node
}
```
**Response**:
```json
{
"sessionId": "uuid",
"problem": "Explain how gradient descent works...",
"nodeTitle": "Gradient Descent",
"planId": "uuid",
"status": "active",
"instructions": {
"audioFormat": "webm",
"submitEndpoint": "/api/agent/session/analyze",
"maxChunkDuration": 60000
}
}
```
### 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`
**Request**:
```json
{
"session_id": "uuid-from-start",
"audio_base64": "base64-encoded-audio-data",
"audio_format": "webm"
}
```
**Response**:
```json
{
"sessionId": "uuid",
"gapScore": 0.7,
"signals": [
"Missing consideration of local minima",
"No mention of learning rate impact"
],
"transcript": "transcribed audio...",
"followUpQuestion": "What happens when the gradient becomes very small?",
"requiresFollowUp": true
}
```
### 4. End Session
Ends an agent session and generates a summary report.
**Endpoint**: `POST /api/agent/session/end`
**Request**:
```json
{
"session_id": "uuid-from-start"
}
```
**Response**:
```json
{
"success": true,
"sessionId": "uuid",
"message": "Session ended and report generated",
"chunkCount": 5,
"wordCount": 1200
}
```
### 5. Get Session Summary
Retrieves the summary report of a completed session.
**Endpoint**: `GET /api/agent/session/summary?session_id=xxx`
**Response (if ready)**:
```json
{
"ready": true,
"sessionId": "uuid",
"report": "# Session Report\n\n## Overview\n...",
"createdAt": "2026-02-24T12:00:00Z",
"status": "completed"
}
```
**Response (if not ready)**:
```json
{
"ready": false,
"message": "Session report not ready yet. Call /session/end first to generate the report.",
"sessionId": "uuid",
"status": "active"
}
```
## Complete Agent Workflow
```python
import base64
import requests
API_KEY = "your_api_key"
BASE_URL = "https://openlesson.academy"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# Step 1: Generate a learning plan (optional: specify days)
plan_response = requests.post(
f"{BASE_URL}/api/agent/plan",
json={
"topic": "Quantum Computing",
"days": 14 # optional: number of days for the plan
},
headers=HEADERS
)
plan = plan_response.json()
# Step 2: Start a session for the first node
first_node = next(n for n in plan["nodes"] if n["is_start"])
session_response = requests.post(
f"{BASE_URL}/api/agent/session/start",
json={"plan_node_id": first_node["id"], "problem": first_node["title"]},
headers=HEADERS
)
session = session_response.json()
# Step 3: Record and analyze audio
# 1. Record audio from user (use browser MediaRecorder or similar)
# 2. Convert to base64
with open("audio.webm", "rb") as f:
audio_base64 = base64.b64encode(f.read()).decode()
analyze_response = requests.post(
f"{BASE_URL}/api/agent/session/analyze",
json={
"session_id": session["sessionId"],
"audio_base64": audio_base64,
"audio_format": "webm"
},
headers=HEADERS
)
analysis = analyze_response.json()
print(f"Gap Score: {analysis['gapScore']}")
print(f"Follow-up: {analysis['followUpQuestion']}")
```
## Error Handling
- **401**: Invalid or inactive API key
- **403**: Session doesn't belong to this key or wrong endpoint
- **404**: Session not found
- **500**: Internal server error
## Tips for Agents
1. **Always use audio**: The analyze endpoint ONLY accepts audio. Never send text.
2. **Record in webm format**: This is the preferred format (Opus codec)
3. **Chunk audio**: Send 30-60 second chunks for analysis
4. **Follow up**: If `requiresFollowUp` is true, ask the follow-up question and record response
5. **Track gap scores**: Use gap score to determine when user has mastered a concept
6. **Use bash -c for curl**: When running API calls in shell scripts, use the `bash -c 'printf "..." | curl ... --data-binary @-'` pattern to avoid JSON escaping issues
7. **Schedule all sessions**: When you generate a learning plan, it is important to schedule all the sessions suggested in the plan for your human. Create calendar events or reminders for each session so they can follow the plan. **Always remind your human when a session is due** - don't wait for them to ask.
don't have the plugin yet? install it then click "run inline in claude" again.