{"openapi": "3.0.3", "info": {"title": "Autonomous Multilingual Store Onboarding Voice Bot API", "description": "Production Faster-Whisper + Chrome Web Speech API Voice Bot backend for onboarding Indian stores in English, Hindi, and Telugu. Automatically extracts, validates, and transliterates conversational speech into structured store JSON.", "version": "1.0.0", "contact": {"name": "Store Onboarding AI Support"}}, "servers": [{"url": "http://localhost:8000", "description": "Local Development Server"}], "tags": [{"name": "Session", "description": "Manage onboarding state, languages, and session reset"}, {"name": "Voice & Transcription", "description": "Speech-to-Text transcription and Text-to-Speech synthesis"}, {"name": "Survey & Correction", "description": "Answer questions, validate inputs, and update store JSON fields"}, {"name": "Tokens & Analytics", "description": "Token usage calculations, subword BPE metrics, and multilingual token benchmarking"}], "paths": {"/api/get_state": {"get": {"tags": ["Session"], "summary": "Get Current Session State", "description": "Returns current onboarding progress, active question, language settings, and live store profile JSON.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Language code for question text ('en', 'hi', 'te')", "schema": {"type": "string", "enum": ["en", "hi", "te"], "default": "en"}}], "responses": {"200": {"description": "Current onboarding state", "content": {"application/json": {"example": {"json": {"id": "comp_b4b298d66d", "companyId": "comp_b4b298d66d", "companyName": "Royal Clothes", "personName": "Ramesh Kumar", "phone": "9876543210", "email": "ramesh@gmail.com", "logoUrl": null, "storeCategory": ["Clothing"], "doorNo": "402", "street": "MG Road", "area": "Gajuwaka", "town": "", "city": "Visakhapatnam", "state": "Andhra Pradesh", "pincode": "530016", "usedReferalCode": null, "createdAt": null, "productCount": 0, "isPhoneMandatoryForBrowsing": false, "isStoreLoginMandatory": false}, "progress": 38, "current_field": {"index": 5, "total": 13, "key": "doorNo", "label": "Door / Shop Number", "question": "What is your door, shop, or flat number? (Optional: say 'skip' if none)", "required": false, "hint": "e.g., 402, Shop 4, Plot 12"}, "language": "te", "language_chosen": true}}}}}}}, "/api/transcribe": {"post": {"tags": ["Voice & Transcription"], "summary": "Transcribe Voice Audio with Dual-Engine Fusion", "description": "Uploads recorded user speech (WebM or WAV), runs Faster-Whisper with 5-beam search, fuses with Chrome Web Speech subtitle if available, removes conversational filler/prefixes, and returns clean English extraction.", "parameters": [{"name": "X-Language", "in": "header", "required": false, "description": "Selected interview language ('en', 'hi', 'te')", "schema": {"type": "string", "enum": ["en", "hi", "te"], "default": "en"}}, {"name": "X-Client-Transcript", "in": "header", "required": false, "description": "URL-encoded real-time transcript from Chrome Web Speech API for dual-engine accuracy cross-verification", "schema": {"type": "string"}}], "requestBody": {"description": "Raw binary audio recorded from user microphone (audio/webm or audio/wav)", "required": true, "content": {"audio/webm": {"schema": {"type": "string", "format": "binary"}}, "audio/wav": {"schema": {"type": "string", "format": "binary"}}}}, "responses": {"200": {"description": "Transcribed text and English extracted value", "content": {"application/json": {"examples": {"teluguName": {"summary": "Telugu Name Answer", "value": {"status": "ready_to_save", "user_text": "నా పేరు రమేష్ కుమార్", "extracted_value": "Ramesh Kumar", "error_msg": null, "bot_text": null, "field_key": "personName", "detected_language": "te", "detected_prob": 1.0, "json": {"companyName": "Royal Clothes", "personName": "", "phone": ""}}}, "hindiShop": {"summary": "Hindi Shop Name Answer", "value": {"status": "ready_to_save", "user_text": "मेरी दुकान रॉयल क्लॉथ्स है", "extracted_value": "Royal Clothes", "error_msg": null, "bot_text": null, "field_key": "companyName", "detected_language": "hi", "detected_prob": 1.0}}, "spokenDigits": {"summary": "Spoken 10-Digit Mobile", "value": {"status": "ready_to_save", "user_text": "తొమ్మిది ఎనిమిది ఏడు ఆరు ఐదు నాలుగు మూడు రెండు ఒకటి సున్నా", "extracted_value": "9876543210", "error_msg": null, "field_key": "phone"}}}}}}}}}, "/api/answer": {"post": {"tags": ["Survey & Correction"], "summary": "Submit Field Answer & Advance to Next Question", "description": "Stores user answer for the current field into live JSON, advances the question index, and returns the next question with TTS audio prompts.", "parameters": [{"name": "X-Language", "in": "header", "required": false, "description": "Active language ('en', 'hi', 'te')", "schema": {"type": "string", "enum": ["en", "hi", "te"], "default": "en"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"key": {"type": "string", "description": "Field key being answered", "example": "personName"}, "answer": {"type": "string", "description": "User spoken or typed answer", "example": "Ramesh Kumar"}, "lang": {"type": "string", "description": "Language code", "example": "en"}}, "required": ["answer"]}, "examples": {"savePersonName": {"summary": "Save Person Name", "value": {"key": "personName", "answer": "Ramesh Kumar", "lang": "en"}}, "skipOptionalField": {"summary": "Skip Optional Field (e.g. Referral Code)", "value": {"key": "usedReferalCode", "answer": "skip", "lang": "te"}}}}}}, "responses": {"200": {"description": "Field saved and next question returned", "content": {"application/json": {"example": {"user_text": "Ramesh Kumar", "bot_text": "Great, saved Contact Person Name. What is your 10-digit mobile number?", "current_field": {"index": 3, "total": 13, "key": "phone", "label": "Phone Number", "question": "What is your 10-digit mobile number?", "required": true}, "progress": 23, "field_key": "personName", "extracted_value": "Ramesh Kumar", "is_completed": false, "json": {"id": "comp_b4b298d66d", "companyName": "Royal Clothes", "personName": "Ramesh Kumar"}}}}}}}}, "/api/correct_field": {"post": {"tags": ["Survey & Correction"], "summary": "Directly Correct or Edit Any JSON Field", "description": "Edits any past or current field directly in the store profile without disrupting current question order.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"key": {"type": "string", "description": "Store JSON field key to edit", "example": "phone"}, "value": {"type": "string", "description": "New updated value", "example": "9876543210"}}, "required": ["key", "value"]}, "examples": {"updatePhone": {"summary": "Update Phone Number", "value": {"key": "phone", "value": "9876543210"}}, "updateCategory": {"summary": "Update Store Category", "value": {"key": "storeCategory", "value": "Clothing, Fashion"}}}}}}, "responses": {"200": {"description": "Field updated successfully", "content": {"application/json": {"example": {"status": "updated", "progress": 30, "json": {"phone": "9876543210", "storeCategory": ["Clothing", "Fashion"]}}}}}}}}, "/api/tts": {"get": {"tags": ["Voice & Transcription"], "summary": "Get Speech Audio (Text-to-Speech MP3)", "description": "Returns pre-warmed or dynamically synthesized MP3 speech audio in Telugu, Hindi, or English.", "parameters": [{"name": "text", "in": "query", "required": true, "description": "Text to synthesize into speech", "schema": {"type": "string"}, "example": "మీ దుకాణం లేదా కంపెనీ పేరు ఏమిటి?"}, {"name": "lang", "in": "query", "required": true, "description": "Language code ('te' for Telugu, 'hi' for Hindi, 'en' for English)", "schema": {"type": "string", "enum": ["te", "hi", "en"], "default": "te"}, "example": "te"}], "responses": {"200": {"description": "Synthesized MP3 audio stream", "content": {"audio/mpeg": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"description": "Missing required text or lang parameter"}}}}, "/api/set_language": {"post": {"tags": ["Session"], "summary": "Set or Switch Active Language", "description": "Switches the interview language between English, Hindi, and Telugu.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"lang": {"type": "string", "enum": ["en", "hi", "te"], "example": "te"}}, "required": ["lang"]}}}}, "responses": {"200": {"description": "Language switched successfully", "content": {"application/json": {"example": {"status": "success", "language": "te", "current_field": {"key": "companyName", "question": "మీ దుకాణం లేదా కంపెనీ పేరు ఏమిటి?"}}}}}}}}, "/api/reset": {"post": {"tags": ["Session"], "summary": "Reset Onboarding Session", "description": "Resets all collected data, generates a new store UUID, and restarts onboarding from Question 1.", "responses": {"200": {"description": "Session reset", "content": {"application/json": {"example": {"status": "reset", "progress": 0, "json": {"id": "comp_a1b2c3d4e5", "companyId": "comp_a1b2c3d4e5", "companyName": "", "personName": "", "phone": ""}}}}}}}}, "/api/calculate_tokens": {"post": {"tags": ["Tokens & Analytics"], "summary": "Calculate Multilingual Subword Token Counts", "description": "Calculates exact BPE tokens (Whisper vocabulary) and returns character, word, and token density statistics for English, Hindi, Telugu, and Tenglish.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"text": {"type": "string", "example": "మీ store లేదా company name ఏంటి?"}}, "required": ["text"]}, "examples": {"teluguText": {"summary": "Tenglish Question", "value": {"text": "మీ store లేదా company name ఏంటి?"}}, "hindiText": {"summary": "Hindi Question", "value": {"text": "आपकी दुकान या कंपनी का नाम क्या है?"}}, "englishText": {"summary": "English Question", "value": {"text": "What is your company or store name?"}}}}}}, "responses": {"200": {"description": "Calculated token statistics", "content": {"application/json": {"example": {"text": "మీ store లేదా company name ఏంటి?", "token_count": 14, "character_count": 34, "word_count": 6, "tokens_per_word": 2.33}}}}}}}}}