​

Ella Backend: API & Database System Inventory

​

Base URL Prefix

​

Interactive API Documentation

• Swagger UI (Production): https://ella.navgurukul.org/api/docs (Local: http://localhost:8000/docs)
• ReDoc (Production): https://ella.navgurukul.org/api/redoc (Local: http://localhost:8000/redoc)

​

Placement & Onboarding Flow API Sequence

1. App Launch & Welcome Screen:
   • POST /auth/anonymous: Automatically invoked in the background to exchange the device’s generated UUID for a secure JWT access token, registering the account if it’s the first run.
2. Placement Screen (Voice screening chat):
   • POST /llm/placement-turn: Called on every message turn (speech or text) containing the conversation history. Zoe replies with the next prompt until sufficient turn evidence is gathered, at which point the API responds with is_complete: true and the evaluated CEFR level results.
3. Transitioning to Result Screen:
   • PUT /users/me: Updates student’s extracted name, age, and location.
   • POST /placements: Persists the final CEFR level assessment, description highlight, hobbies, and conversation transcript.

​

Client App API Integration Summary

​

1. Database Schema & Models

​

A. Users Table (user.py)

​

B. Placements Table (placement.py)

​

C. Conversations Table (conversation.py)

​

D. Messages Table (message.py)

​

E. Session Analyses Table (session_analysis.py)

​

2. API Endpoints Catalog & Purpose Specs

​

Group 1: Onboarding & Authentication

• POST https://ella.navgurukul.org/api/auth/anonymous
  • Payload: AnonymousAuthRequest (device_id string)
  • Purpose & Reason: Establishes a zero-friction user account on first app install. We want to avoid requiring emails or passwords for young students. If the device_id is new, it silently provisions a new SQL record in users and issues a JSON Web Token (JWT). If the device is returning, it issues a fresh token to authenticate subsequent calls.

​

Group 2: User Profiles & Learning Settings

• GET https://ella.navgurukul.org/api/users/me
  • Headers: Authorization: Bearer <token>
  • Purpose & Reason: Fetches the student’s active status (level, tags, and settings). This is called when the app starts to check if the student has completed their first voice placement screening.
• PUT https://ella.navgurukul.org/api/users/me
  • Payload: UpdateProfileRequest (name, age, location)
  • Purpose & Reason: Captures details parsed from LLM placement transcripts. It updates demographic details on the student’s profile for localized progress grouping.

​

Group 3: Voice Placement Screening Loop

• POST https://ella.navgurukul.org/api/llm/placement-turn
  • Payload: PlacementTurnRequest (messages, name, age)
  • Purpose & Reason: Runs the 3-turn voice screening test. Zoe greets the student and conducts a conversational prompt flow. The API acts as the state machine; once 3 turns are completed, it evaluates CEFR proficiency and sets is_complete=True.
• POST https://ella.navgurukul.org/api/placements
  • Payload: CreatePlacementRequest (level, level_label, confidence, highlight, transcript_json, interests)
  • Purpose & Reason: Finalizes the placement test. Saves the final CEFR grading, logs confidence scoring, extracts interest tags, and stores the chat transcript JSON. It updates the student’s profile settings to lock in their learning level.
• GET https://ella.navgurukul.org/api/placements/latest
  • Purpose & Reason: Fetches the student’s active placement parameters to adjust vocabulary and theme choices.
• GET https://ella.navgurukul.org/api/placements
  • Purpose & Reason: Lists historical placement tests completed, allowing progress comparisons over time.

​

Group 4: Call Sessions & Active Voice Chat

• POST https://ella.navgurukul.org/api/session
  • Payload: CreateConversationRequest (topic)
  • Purpose & Reason: Creates a new session container. Binds the selected learning theme (e.g. “My Family”) to a unique session ID, allowing us to group subsequent message turns under one session.
• POST https://ella.navgurukul.org/api/session/{session_id}/turn
  • Payload: ConversationTurnRequest (content)
  • Purpose & Reason: The core turn-by-turn conversational logic. For every sentence the student speaks, this endpoint processes the message, runs context analysis, and returns Zoe’s response.
• POST https://ella.navgurukul.org/api/session/{session_id}/messages
  • Payload: StoreMessageRequest (role, content, correction, stt_duration_ms, llm_duration_ms, tts_duration_ms, turn_number)
  • Purpose & Reason: Persists individual message bubbles, corrections, and latency metrics to database history.
• GET https://ella.navgurukul.org/api/session/{session_id}/messages
  • Purpose & Reason: Returns the transcript history of a call to display the chat list UI.
• GET https://ella.navgurukul.org/api/session/{session_id}/analysis
  • Purpose & Reason: Returns qualitative and quantitative evaluation of the session once completed.
• GET https://ella.navgurukul.org/api/session/{session_id}/session-log
  • Purpose & Reason: Returns the compiled structured log for learning analytics.

​

Group 5: Post-Session Evaluation & Progress

• POST https://ella.navgurukul.org/api/llm/session-analysis
  • Payload: SessionAnalysisRequest
  • Purpose & Reason: Runs immediately after session completion. Zoe analyzes the full transcript, extracting a “Best Moment” and “Courage” moments to build encouragement cards. The endpoint automatically computes practice duration dynamically as learner_turns * 30 seconds and saves it to the database, completing the conversation.
• GET https://ella.navgurukul.org/api/progress/summary
  • Purpose & Reason: Computes aggregate statistics (total calls, completed sessions, speaking time, and placement history) to display on the student’s profile dashboard.

​

Group 6: Classroom Admin Dashboards (Key Protected)

• GET https://ella.navgurukul.org/api/admin/stats
  • Purpose & Reason: Provides classroom stats (user levels, total minutes spoken) for supervisor auditing (requires query string key).
• GET https://ella.navgurukul.org/api/admin/conversations/{conversation_id}/transcript
  • Purpose & Reason: Allows supervisors to fetch full transcripts with detailed latency profiles to review student progress (requires admin key).
• GET https://ella.navgurukul.org/api/admin/placements/{user_id}/transcript
  • Purpose & Reason: Allows supervisors to review the transcript of a student’s placement test to audit grading accuracy (requires admin key).

​

Group 7: Accent Evaluation (POC — Disabled)

• POST https://ella.navgurukul.org/api/accent/predict
  • Payload: UploadFile (Multipart WAV Audio)
  • Purpose & Reason: Implements an accent prediction POC. Takes WAV audio files, extracts MFCC features using librosa, and uses a trained Keras CNN model (accent_model.h5) to classify the accent as Indian or American. (Currently commented out in main app due to heavy machine learning dependencies).

​

Group 8: System Diagnostics

• GET https://ella.navgurukul.org/api/
  • Purpose & Reason: Verifies the API server is reachable and redirects to OpenAPI specs.
• GET https://ella.navgurukul.org/api/health
  • Purpose & Reason: Basic health check endpoint for DevOps monitoring.

​

3. Practical API Curl Examples

​

1. Anonymous Device Registration (Token Exchange)

curl -X POST https://ella.navgurukul.org/api/auth/anonymous \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "8c59-cc44-b71a-40e9-uuid"
  }'

​

2. Fetch User Profile Details

curl -X GET https://ella.navgurukul.org/api/users/me \
  -H "Authorization: Bearer <your_access_token>"

​

3. Start a Session

curl -X POST https://ella.navgurukul.org/api/session \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "My Favorite Sports"
  }'

​

4. Execute a Conversation Turn (Zoe’s Response)

curl -X POST https://ella.navgurukul.org/api/llm/conversation-turn \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "3be40648-1fd1-4942-b96f-44c3a02344db",
    "messages": [
      {
        "role": "user",
        "content": "hello zoe i like to play cricket with my friends"
      }
    ],
    "topic": "My Favorite Sports",
    "level": "A1",
    "level_label": "Getting Started",
    "current_turn": 1
  }'

​

5. Log Message Turn (Telemetry and Corrections)

curl -X POST https://ella.navgurukul.org/api/session/3be40648-1fd1-4942-b96f-44c3a02344db/messages \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "hello zoe i like to play cricket with my friends",
    "correction": "Hello Zoe, I like playing cricket with my friends.",
    "stt_duration_ms": 320,
    "llm_duration_ms": 1100,
    "tts_duration_ms": 500,
    "turn_number": 1
  }'

​

6. Generate Post-Session Analysis

curl -X POST https://ella.navgurukul.org/api/llm/session-analysis \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "3be40648-1fd1-4942-b96f-44c3a02344db",
    "messages": [
      {
        "role": "user",
        "content": "hello zoe i like to play cricket with my friends"
      },
      {
        "role": "assistant",
        "content": "Cricket is great! Who is your favorite player?"
      }
    ],
    "topic": "My Favorite Sports",
    "level": "A1",
    "level_label": "Getting Started"
  }'

​

7. Retrieve Classroom Stats Dashboard (Admin Route)

curl -X GET "https://ella.navgurukul.org/api/admin/stats?key=<your_admin_secret_key>"