Skip to content

API.md

Latest commit

 

History

History
86 lines (66 loc) · 3.79 KB

API.md

File metadata and controls

86 lines (66 loc) · 3.79 KB
Raw

API

Base path /api. Bearer token in Authorization, or the httpOnly cookie set at login. Interactive docs at /docs outside production.

Auth

Method Path Notes
POST /auth/register Creates the account, profile and settings
POST /auth/login Returns an access token; sets refresh cookie
POST /auth/refresh Rotates the refresh token — single use
POST /auth/logout Revokes the refresh token
POST /auth/password-reset/request Always 202, never reveals whether the account exists
POST /auth/password-reset/confirm Revokes all sessions on success
GET/PATCH /auth/me, /auth/me/profile, /auth/me/settings

Sessions

Method Path Notes
POST /session/start Returns the session and the coach's opening line
POST /session/{id}/message One coached turn
POST /session/{id}/end Summary, streak and totals
GET /session/{id}, /session Transcript; recent sessions

A turn returns the coach's reply plus corrections[] (original / corrected / natural / professional / executive, category, severity, explanation), practice_required, repeat_sentence, follow_up_question, and measured fillers. The structured payload is rendered as UI — never shown as raw JSON.

Speech

Method Path Notes
GET /speech/providers Where speech runs; whether the client transcribes
POST /speech/transcribe Audio or a browser transcript. With create_turn=true this is the whole voice loop in one call
POST /speech/evaluate Scores an answer, bounded by what was measured
POST /speech/tts Audio, or voice settings for client-side synthesis

Learning

GET /dashboard · GET /learning-plan · GET /learning-plan/today?quick= · POST /learning-plan/day/{n}/regenerate|complete|mission · GET/POST /vocabulary · POST /vocabulary/{id}/review · POST /phrases · GET /mistakes · GET /mistakes/recurring · GET /progress · GET /progress/series/{skill} · POST /progress/rollup

Training

GET/PUT /training/thinking, POST /training/thinking/advance · POST /training/rapid/start, /rapid/{id}/answer · POST /training/shadowing/line, /shadowing/attempt · POST /training/challenge/start, /challenge/{id}/submit · GET /training/storytelling/prompt, POST /training/storytelling/analyse · GET /training/explain/topics, /explain/plan, /listening · GET /training/roleplay/scenarios, POST /training/roleplay/start, /roleplay/{id}/turn, /roleplay/{id}/debrief · POST /training/interview/start, /emergency/start · GET /training/disagreement/drills, POST /training/disagreement/check

Assessment and reports

GET /assessment/sections (includes the published CEFR bands and score weights) · POST /assessment/start, /{id}/submit, /{id}/complete · GET /assessment/results · GET /reports/daily|weekly|history|comparison|final|certificate · GET /achievements, POST /achievements/evaluate

Privacy

GET /privacy/export · DELETE /privacy/conversations|recordings|memory · POST /privacy/account/delete (password required) · POST /privacy/logout-everywhere

Admin (admin accounts only)

GET /admin/users, PATCH /admin/users/{id} · GET/PUT /admin/prompts[/{name}] · GET /admin/providers|config|usage|audit|scenarios|vocabulary · PATCH /admin/scenarios/{code} · POST /admin/vocabulary

Conventions

  • Ownership failures return 404, not 403, so IDs are not confirmed.
  • Metrics always carry confidence and method; value: null with confidence: "unavailable" is a valid, expected answer.
  • Rate limits: 10/min auth, 60/min speech and turns, 20/min destructive privacy.
  • Errors are {"detail": "..."}. Validation errors are FastAPI's 422 shape.