Skip to main content

📡 API Documentation

LinguFlow exposes a RESTful JSON API implemented using FastAPI. All endpoints are prefixed with /api.

Interactive API documentation is automatically available at runtime:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

🔒 Authentication Headers​

Protected endpoints require a valid JWT bearer token in the HTTP request header:

Authorization: Bearer <your_jwt_access_token>

1. Authentication Endpoints (/api/auth)​

MethodEndpointDescriptionProtected
POST/api/auth/registerRegister new account with email & passwordNo
POST/api/auth/loginAuthenticate user with credentialsNo
POST/api/auth/guestInstant guest login (returns temporary guest token)No
POST/api/auth/googleAuthenticate via Google OAuth2 ID tokenNo
POST/api/auth/forgot-passwordRequest password reset verification linkNo
GET/api/auth/meFetch authenticated user profileYes

Request & Response Schemas​

POST /api/auth/register​

Request Body:

{
"username": "candidate1",
"email": "candidate1@example.com",
"password": "Password123!"
}

Response (201 Created):

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "c1f7b8e2-9d3a-4e2b-8a1f-0b2c3d4e5f6a",
"username": "candidate1",
"email": "candidate1@example.com",
"isGuest": false
}
}

2. Flashcard & SM-2 Endpoints (/api/cards)​

MethodEndpointDescriptionProtected
GET/api/cards/studyFetch cards due for review (srs_next_review <= now())Yes
POST/api/cards/review/{id}Process review score (1-4) via SM-2 algorithmYes
GET/api/cardsList all flashcards owned by userYes
POST/api/cardsCreate a new flashcardYes
PUT/api/cards/{id}Update flashcard prompt or definitionYes
DELETE/api/cards/{id}Delete flashcardYes

Card Response Format (CamelCase srsData Contract)​

{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d4e5",
"userId": "c1f7b8e2-9d3a-4e2b-8a1f-0b2c3d4e5f6a",
"deckId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"front": "Ephemeral",
"back": "Lasting for a very short time",
"srsData": {
"interval": 1,
"easeFactor": 2.5,
"repetitions": 1,
"nextReviewDate": "2026-08-05T00:00:00Z"
},
"createdAt": "2026-08-04T00:00:00Z",
"updatedAt": "2026-08-04T00:00:00Z"
}

3. Deck Management Endpoints (/api/decks)​

MethodEndpointDescriptionProtected
GET/api/decksList all decks owned by user with aggregated cardCountYes
POST/api/decksCreate a new study deckYes
PUT/api/decks/{id}Update deck name and descriptionYes
DELETE/api/decks/{id}Delete deck (unlinks attached cards)Yes

Deck Response Format​

{
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"userId": "c1f7b8e2-9d3a-4e2b-8a1f-0b2c3d4e5f6a",
"name": "TOEIC Essential Vocabulary",
"description": "High-frequency Part 5 & 6 words",
"cardCount": 42,
"createdAt": "2026-08-04T00:00:00Z",
"updatedAt": "2026-08-04T00:00:00Z"
}

4. Exams, Attempts & Practice (/api/exams, /api/attempts, /api/practice)​

Assessment v2 surface. Full invariants: Question & Exam Design. Practice drills: Practice Mode.

MethodEndpointDescriptionProtected
GET/api/examsList visible exams (disabled types omitted)Optional
POST/api/examsCreate draft examYes
GET/api/exams/{id}Exam detailOptional / ownership
GET PUT/api/exams/{id}/draftWorking structureYes (edit)
POST/api/exams/{id}/publishFreeze an ExamVersionYes
GET PUT/api/exams/{id}/sharingSharing stateYes
POST/api/attemptsStart exam attempt (403 if type disabled)Yes
GET/api/attemptsCaller’s attemptsYes
GET/api/attempts/{id}Attempt paper / statusYes
PUT/api/attempts/{id}/responsesSave answersYes
POST/api/attempts/{id}/pause · /resumePause clockYes
POST/api/attempts/{id}/finishScore & completeYes
GET/api/attempts/{id}/resultsMulti-scale scores + reviewYes
POST/api/practice/from-examPractice draw from an examYes (non-guest)
POST/api/practice/from-bankPractice draw from bank filtersYes (non-guest)
POST/api/practice/drills/{id}/resitResit a practice drillYes (non-guest)
PUT/api/practice/notesUpsert per-question noteYes

5. Exam-Type Feature Flags (/api/exam-types)​

MethodEndpointDescriptionProtected
GET/api/exam-typesEnabled/disabled state for every flag-controlled exam typeNo

Response — key matches an exams.exam_type value; a type absent from this list is enabled by default:

[
{ "key": "toeic", "enabled": true },
{ "key": "hsk", "enabled": false }
]

See Exam-Type Feature Flags for the enforcement model (what disabling a type actually blocks) and the operator guide for toggling one.


6. Feature Flags (/api/feature-flags)​

Product-wide kill switches. Same “missing row = enabled” rule as exam-type flags. See AI Service Layer for the ai flag.

MethodEndpointDescriptionProtected
GET/api/feature-flagsAll product flags (key, enabled)No
PATCH/api/feature-flags/{key}Toggle a known flag (ai)Root admin

7. AI Endpoints (/api/ai)​

Registered non-guest users only. Guests get 403. Provider failures and the ai kill switch return 503 (never 500). Full contracts, cache, and jobs: AI Service Layer. Learner guide: AI Features.

MethodEndpointDescriptionProtected
POST/api/ai/explain-cardExplain a card the caller ownsYes (non-guest)
POST/api/attempts/{id}/items/{position}/explainExplain a pinned attempt item (completed, or practice)Yes (non-guest)
POST/api/ai/generate-questionsEnqueue generation (202 { jobId })Yes (non-guest)
GET/api/ai/jobs/{jobId}Poll a job the caller ownsYes (non-guest)

8. Question Bank Endpoints (/api/questions, /api/stimuli)​

Questions are a shared bank, not exam property. Exam placement is exam_slots on a published exam_version. Media lives in DSL blocks on stimulus/question versions — see TOEIC Listening Items and Question & Exam Design.

MethodEndpointDescriptionProtected
GET/api/questionsList / filter the live bankOptional
POST/api/questionsCreate a question (draft)Yes
GET/api/questions/facetsFilter vocabulariesOptional
GET/api/questions/{id}Fetch one bank questionOptional / ACL
PUT/api/questions/{id}Update draft / editable fieldsYes
POST/api/questions/{id}/publishPublish current versionYes
DELETE/api/questions/{id}Soft-delete (archived_at)Yes
GET/api/questions/{id}/previewPreview payloadOptional / ACL
GET PUT/api/questions/{id}/sharingSharing stateYes
GET PUT DELETE/api/stimuli/{id}Shared stimulus CRUDACL
GET/api/stimuli/{id}/questionsStems linked to a stimulusACL

9. Real-Time & Media Endpoints​

MethodEndpointDescriptionProtected
POST/api/media/presign-uploadSign a PUT. Body purpose: "card" (default) or "question"Yes
POST/api/media/confirm-uploadValidate staging object; copy to cards/… or questions/…Yes
GET/api/media/presign-download/{file_key}Sign a GET for a final owner key onlyYes
DELETE/api/media/{file_key}Delete staging or unattached final object (409 if a card or question still references it)Yes
GET/api/healthHealth check endpoint ({"status": "ok"})No

Question uploads must send purpose: "question" (audio + image types). Card uploads stay image-only. Pipeline and CORS: Card Image Uploads.