Piggyback Learning API

• auth
  • postVerify admin/expert password (legacy)
  • postAdmin login with ADMIN_PASSWORD
  • postParent/expert login with personal access code
  • postExpert logout
  • postChild login - enter parent access code and get linked child profiles
• kids
  • getGet children assigned to an expert
  • getGet report for a child
  • getGet videos available for a child
  • getList all locally available videos for kids
  • getGet final approved questions for a video
  • postEvaluate a child's voice answer against the expected answer
  • postTranscribe uploaded audio to text
  • postSave a completed quiz attempt for a child
  • getGet all quiz attempts for a child
  • getGet frontend quiz configuration (thresholds, skip prevention)
• expert
  • getGet the logged-in expert's current access code
  • putUpdate the logged-in expert's own login code
  • getList all parents managed by the logged-in expert
  • getList children linked to a parent
  • putUpdate a parent's login/access code
  • getGet the child progress report for the logged-in expert
  • getList all processed videos available to experts
  • getList videos not yet claimed by any expert
  • postClaim a video for expert review
  • delUnclaim a video from the expert
  • getGet final questions for a video
  • postSave edited questions for a video
  • postRegenerate a single question for a video using AI
  • getGet companion-variant questions for a video
  • postGenerate companion-variant questions for a video
  • postGenerate companion-variant questions from a question list
  • getList downloaded videos (shared expert/admin view)
  • getGet AI-generated questions for a video (pre-review)
  • postSave expert question payload
  • postSave final expert-approved questions
  • postSave expert annotations payload
  • getExpert edit page for a video (HTML)
• admin
  • getList all expert accounts
  • postCreate a new expert account
  • putUpdate an expert account
  • delDelete an expert account
  • postDeactivate an expert account
  • getList all children
  • postCreate a new child profile
  • putUpdate a child profile
  • delDelete a child profile
  • postDeactivate a child profile
  • postUnlink a child from their parent
  • getList all downloaded videos with frame/question status
  • getList video-to-expert assignments
  • postAssign a video to an expert
  • postDownload a YouTube video via yt-dlp
  • postExtract frames from a downloaded video
  • postSubmit AI-generated questions for a video
  • getGet full report for a child (admin view)
• media
  • postGenerate TTS audio

API docs by Redocly

Piggyback Learning API (0.2.0)

Download OpenAPI specification:Download

OpenAPI contract for Piggyback Learning FastAPI backend. Auth uses session cookies: parent/expert login via POST /api/expert/login, child login via POST /api/learners/parents/login, admin via POST /api/admin/verify-access.

auth

Login and logout for all roles

Verify admin/expert password (legacy)

Request Body schema: application/x-www-form-urlencoded

user_type required	string Enum: "admin" "expert"
password required	string

Responses

Local development server

http://localhost:8000/api/verify-password

Response samples

• 200
• 422

Content type

application/json

{

• "success": true,
• "redirect": "string",
• "message": "string"

}

Admin login with ADMIN_PASSWORD

Request Body schema: application/json

password required

string

Responses

Local development server

http://localhost:8000/api/admin/verify-access

Request samples

• Payload

Content type

application/json

{

• "password": "string"

}

Response samples

• 200
• 401

Content type

application/json

{ }

Parent/expert login with personal access code

Request Body schema: application/json

access_code required

string

Responses

Local development server

http://localhost:8000/api/expert/login

Request samples

• Payload

Content type

application/json

{

• "access_code": "string"

}

Response samples

• 200
• 401

Content type

application/json

{ }

Expert logout

Responses

Local development server

http://localhost:8000/api/expert/logout

Response samples

• 200

Content type

application/json

{ }

Child login - enter parent access code and get linked child profiles

Request Body schema: application/json

access_code required

string

Responses

Local development server

http://localhost:8000/api/learners/parents/login

Request samples

• Payload

Content type

application/json

{

• "access_code": "string"

}

Response samples

• 200
• 401

Content type

application/json

{ }

kids

Child-facing quiz and video routes

Get children assigned to an expert

path Parameters

expert_id required

string

Responses

Local development server

http://localhost:8000/api/learners/experts/{expert_id}/children

Response samples

• 200

Content type

application/json

{ }

Get report for a child

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/learners/children/{child_id}/report

Response samples

• 200

Content type

application/json

{ }

Get videos available for a child

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/learners/children/{child_id}/videos

Response samples

• 200

Content type

application/json

{ }

List all locally available videos for kids

Responses

Local development server

http://localhost:8000/api/kids_videos

Response samples

• 200

Content type

application/json

{

• "success": true,
• "count": 0,
• "videos": [

  • {

    • "video_id": "string",
    • "title": "string",
    • "duration": "string",
    • "local_path": "string",
    • "thumbnail": "string"

    }

  ]

}

Get final approved questions for a video

path Parameters

video_id required

string

query Parameters

companion

string Enum: "bunny" "pig" "alligator"

Responses

Local development server

http://localhost:8000/api/final-questions/{video_id}

Response samples

• 200

Content type

application/json

{

• "success": true,
• "segments": [

  • {

    • "segment_range_start": 0,
    • "segment_range_end": 0,
    • "question": "string",
    • "answer": "string",
    • "llm_ranking": 0,
    • "expert_ranking": 0

    }

  ],
• "error": "string"

}

Evaluate a child's voice answer against the expected answer

Request Body schema: application/json

expected required	string
user required	string
question	string

Responses

Local development server

http://localhost:8000/api/check_answer

Request samples

• Payload

Content type

application/json

{

• "expected": "string",
• "user": "string",
• "question": "string"

}

Response samples

• 200

Content type

application/json

{

• "similarity": 0,
• "expected": "string",
• "user": "string",
• "is_numeric": true,
• "status": "correct",
• "reason": "string"

}

Transcribe uploaded audio to text

Request Body schema: multipart/form-data

file required

string <binary>

Responses

Local development server

http://localhost:8000/api/transcribe

Response samples

• 200

Content type

application/json

{

• "success": true,
• "text": "string",
• "error": "string"

}

Save a completed quiz attempt for a child

Request Body schema: application/json

child_id required	string
video_id required	string
percentage	number
total_retries	integer
watch_minutes	number
interaction_mode	string
	Array of objects

Responses

Local development server

http://localhost:8000/api/save-quiz-score

Request samples

• Payload

Content type

application/json

{

• "child_id": "string",
• "video_id": "string",
• "percentage": 0,
• "total_retries": 0,
• "watch_minutes": 0,
• "interaction_mode": "string",
• "details": [

  • { }

  ]

}

Response samples

• 200

Content type

application/json

{ }

Get all quiz attempts for a child

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/get-quiz-scores/{child_id}

Response samples

• 200

Content type

application/json

{ }

Get frontend quiz configuration (thresholds, skip prevention)

Responses

Local development server

http://localhost:8000/api/config

Response samples

• 200

Content type

application/json

{

• "skip_prevention": true,
• "thresholds": { }

}

expert

Parent/expert question review and video management

Get the logged-in expert's current access code

Responses

Local development server

http://localhost:8000/api/expert/access-code

Response samples

• 200

Content type

application/json

{ }

Update the logged-in expert's own login code

Request Body schema: application/json

login_code required

string

Responses

Local development server

http://localhost:8000/api/expert/my-login-code

Request samples

• Payload

Content type

application/json

{

• "login_code": "string"

}

Response samples

• 200

Content type

application/json

{ }

List all parents managed by the logged-in expert

Responses

Local development server

http://localhost:8000/api/expert/parents

Response samples

• 200

Content type

application/json

{ }

List children linked to a parent

path Parameters

parent_id required

string

Responses

Local development server

http://localhost:8000/api/expert/parents/{parent_id}/children

Response samples

• 200

Content type

application/json

{ }

Update a parent's login/access code

path Parameters

parent_id required

string

Request Body schema: application/json

login_code required

string

Responses

Local development server

http://localhost:8000/api/expert/parents/{parent_id}/login-code

Request samples

• Payload

Content type

application/json

{

• "login_code": "string"

}

Response samples

• 200

Content type

application/json

{ }

Get the child progress report for the logged-in expert

Responses

Local development server

http://localhost:8000/api/expert/report

Response samples

• 200

Content type

application/json

{ }

List all processed videos available to experts

Responses

Local development server

http://localhost:8000/api/expert/videos

Response samples

• 200

Content type

application/json

{ }

List videos not yet claimed by any expert

Responses

Local development server

http://localhost:8000/api/expert/videos/available

Response samples

• 200

Content type

application/json

{ }

Claim a video for expert review

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/expert/videos/{video_id}/claim

Response samples

• 200

Content type

application/json

{ }

Unclaim a video from the expert

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/expert/videos/{video_id}/unclaim

Response samples

• 200

Content type

application/json

{ }

Get final questions for a video

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/expert/video/{video_id}/final-questions

Response samples

• 200

Content type

application/json

{

• "success": true,
• "segments": [

  • {

    • "segment_range_start": 0,
    • "segment_range_end": 0,
    • "question": "string",
    • "answer": "string",
    • "llm_ranking": 0,
    • "expert_ranking": 0

    }

  ],
• "error": "string"

}

Save edited questions for a video

path Parameters

video_id required

string

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert/video/{video_id}/update-questions

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Regenerate a single question for a video using AI

path Parameters

video_id required

string

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert/video/{video_id}/regenerate-question

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Get companion-variant questions for a video

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/expert/video/{video_id}/persona-variants

Response samples

• 200

Content type

application/json

{ }

Generate companion-variant questions for a video

path Parameters

video_id required

string

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert/video/{video_id}/persona-variants

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Generate companion-variant questions from a question list

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert/questions/persona-variants

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

List downloaded videos (shared expert/admin view)

Responses

Local development server

http://localhost:8000/api/videos-list

Response samples

• 200

Content type

application/json

{

• "success": true,
• "videos": [

  • {

    • "id": "string",
    • "title": "string",
    • "thumbnail": "string",
    • "duration": 0,
    • "videoUrl": "string",
    • "questionCount": 0

    }

  ],
• "message": "string"

}

Get AI-generated questions for a video (pre-review)

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/expert-questions/{video_id}

Response samples

• 200
• 404

Content type

application/json

{ }

Save expert question payload

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert-questions

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 400

Content type

application/json

{ }

Save final expert-approved questions

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/save-final-questions

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200
• 400

Content type

application/json

{ }

Save expert annotations payload

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/expert-annotations

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Expert edit page for a video (HTML)

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/expert/edit/{video_id}

admin

Admin-only routes for video processing and account management

List all expert accounts

Responses

Local development server

http://localhost:8000/api/admin/experts

Response samples

• 200

Content type

application/json

{ }

Create a new expert account

Request Body schema: application/json

expert_id required	string
display_name required	string
password required	string

Responses

Local development server

http://localhost:8000/api/admin/experts

Request samples

• Payload

Content type

application/json

{

• "expert_id": "string",
• "display_name": "string",
• "password": "string"

}

Response samples

• 200

Content type

application/json

{ }

Update an expert account

path Parameters

expert_id required

string

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/admin/experts/{expert_id}

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Delete an expert account

path Parameters

expert_id required

string

Responses

Local development server

http://localhost:8000/api/admin/experts/{expert_id}

Response samples

• 200

Content type

application/json

{ }

Deactivate an expert account

path Parameters

expert_id required

string

Responses

Local development server

http://localhost:8000/api/admin/experts/{expert_id}/deactivate

Response samples

• 200

Content type

application/json

{ }

List all children

query Parameters

expert_id	string
include_inactive	boolean

Responses

Local development server

http://localhost:8000/api/admin/children

Response samples

• 200

Content type

application/json

{ }

Create a new child profile

Request Body schema: application/json

expert_id required	string
first_name required	string
last_name	string
icon_key	string
interaction_mode	string Enum: "strict" "flexible" "passive"

Responses

Local development server

http://localhost:8000/api/admin/children

Request samples

• Payload

Content type

application/json

{

• "expert_id": "string",
• "first_name": "string",
• "last_name": "string",
• "icon_key": "string",
• "interaction_mode": "strict"

}

Response samples

• 200

Content type

application/json

{ }

Update a child profile

path Parameters

child_id required

string

Request Body schema: application/json

property name* additional property

any

Responses

Local development server

http://localhost:8000/api/admin/children/{child_id}

Request samples

• Payload

Content type

application/json

{ }

Response samples

• 200

Content type

application/json

{ }

Delete a child profile

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/admin/children/{child_id}

Response samples

• 200

Content type

application/json

{ }

Deactivate a child profile

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/admin/children/{child_id}/deactivate

Response samples

• 200

Content type

application/json

{ }

Unlink a child from their parent

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/admin/children/{child_id}/unlink

Response samples

• 200

Content type

application/json

{ }

List all downloaded videos with frame/question status

query Parameters

include_without_frames

boolean

Responses

Local development server

http://localhost:8000/api/admin/videos

Response samples

• 200

Content type

application/json

{

• "success": true,
• "count": 0,
• "videos": [

  • {

    • "video_id": "string",
    • "title": "string",
    • "duration_seconds": 0,
    • "duration_formatted": "string",
    • "has_frames": true,
    • "frame_count": 0,
    • "has_questions": true,
    • "frames_dir": "string",
    • "question_file": "string"

    }

  ],
• "message": "string"

}

List video-to-expert assignments

Responses

Local development server

http://localhost:8000/api/admin/videos/assignments

Response samples

• 200

Content type

application/json

{ }

Assign a video to an expert

Request Body schema: application/json

video_id required	string
expert_id required	string

Responses

Local development server

http://localhost:8000/api/admin/videos/assignments

Request samples

• Payload

Content type

application/json

{

• "video_id": "string",
• "expert_id": "string"

}

Response samples

• 200

Content type

application/json

{ }

Download a YouTube video via yt-dlp

Request Body schema: application/x-www-form-urlencoded

url required

string

Responses

Local development server

http://localhost:8000/api/download

Response samples

• 200

Content type

application/json

{

• "success": true,
• "message": "string",
• "video_id": "string",
• "title": "string",
• "thumbnail": "string",
• "files": [

  • "string"

  ],
• "duration": 0,
• "local_path": "string",
• "subtitle_warning": "string",
• "error_code": "string",
• "recovery_hint": "string",
• "auth_source": "browser",
• "used_player_client": [

  • "string"

  ]

}

Extract frames from a downloaded video

path Parameters

video_id required

string

Responses

Local development server

http://localhost:8000/api/frames/{video_id}

Response samples

• 200

Content type

application/json

{

• "success": true,
• "message": "string",
• "files": [

  • "string"

  ],
• "video_id": "string",
• "output_dir": "string",
• "count": 0

}

Submit AI-generated questions for a video

Request Body schema: application/json

video_id required	string
required	Array of objects

Responses

Local development server

http://localhost:8000/api/submit-questions

Request samples

• Payload

Content type

application/json

{

• "video_id": "string",
• "questions": [

  • { }

  ]

}

Response samples

• 200

Content type

application/json

{

• "success": true,
• "message": "string",
• "file_url": "string",
• "file_path": "string"

}

Get full report for a child (admin view)

path Parameters

child_id required

string

Responses

Local development server

http://localhost:8000/api/reports/child/{child_id}

Response samples

• 200

Content type

application/json

{ }

media

Text-to-speech and media utilities

Generate TTS audio

Request Body schema: application/json

text required	string
voice	string Default: "sage"
speed	number Default: 0.75
format	string Default: "mp3"

Responses

Local development server

http://localhost:8000/api/tts

Request samples

• Payload

Content type

application/json

{

• "text": "string",
• "voice": "sage",
• "speed": 0.75,
• "format": "mp3"

}

Response samples

• 200
• 400
• 502

Content type

application/json

{

• "success": true,
• "audio": "string",
• "format": "string",
• "voice": "string",
• "message": "string"

}