{"openapi":"3.1.0","info":{"title":"Sahay Backend","description":"Sahay — Public-Service & Crisis Assistance Navigator Backend","version":"0.1.0"},"paths":{"/health":{"get":{"summary":"Health Check","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/chat":{"post":{"tags":["Chat"],"summary":"Chat Endpoint","operationId":"chat_endpoint_api_v1_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SahayResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tools":{"get":{"tags":["Tools & TTE"],"summary":"List Tools","operationId":"list_tools_api_v1_tools_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ToolDefinition"},"type":"array","title":"Response List Tools Api V1 Tools Get"}}}}}}},"/api/v1/tte/propose":{"post":{"tags":["Tools & TTE"],"summary":"Propose Tte Tool","operationId":"propose_tte_tool_api_v1_tte_propose_post","parameters":[{"name":"tool_name","in":"query","required":true,"schema":{"type":"string","title":"Tool Name"}},{"name":"problem_context","in":"query","required":true,"schema":{"type":"string","title":"Problem Context"}},{"name":"generated_code","in":"query","required":true,"schema":{"type":"string","title":"Generated Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTEProposal"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/tte/approve":{"post":{"tags":["Tools & TTE"],"summary":"Approve Tte Tool","operationId":"approve_tte_tool_api_v1_tte_approve_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTEApproveRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDefinition"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/schemes":{"get":{"tags":["Services & Schemes"],"summary":"List Public Schemes","operationId":"list_public_schemes_api_v1_schemes_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter schemes by category","title":"Category"},"description":"Filter schemes by category"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response List Public Schemes Api V1 Schemes Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/schemes/{scheme_id}":{"get":{"tags":["Services & Schemes"],"summary":"Get Public Scheme","operationId":"get_public_scheme_api_v1_schemes__scheme_id__get","parameters":[{"name":"scheme_id","in":"path","required":true,"schema":{"type":"string","title":"Scheme Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Public Scheme Api V1 Schemes  Scheme Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/health":{"get":{"summary":"Health Check","operationId":"health_check_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"summary":"Health Check","operationId":"health_check_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api":{"get":{"summary":"Root","operationId":"root_api_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ActionStep":{"properties":{"step_number":{"type":"integer","minimum":1.0,"title":"Step Number","description":"Sequence order of action step"},"title":{"type":"string","title":"Title","description":"Short action summary"},"description":{"type":"string","title":"Description","description":"Detailed instructions for the user"},"estimated_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Time","description":"Expected duration (e.g. 15 mins, 2 days)"}},"type":"object","required":["step_number","title","description"],"title":"ActionStep"},"ChatRequest":{"properties":{"message":{"type":"string","maxLength":10000,"minLength":1,"title":"Message","description":"Natural language situation description"},"conversation_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Conversation Id","description":"Optional session conversation identifier"},"user_context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"User Context","description":"Optional extra user facts"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Optional state / district / region"}},"type":"object","required":["message"],"title":"ChatRequest"},"ConversationDecision":{"properties":{"intent":{"type":"string","title":"Intent","description":"Classified intent (e.g. WEATHER, PUBLIC_SERVICE, CRISIS)"},"sub_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Intent","description":"Classified sub-intent (e.g. FORECAST, FOOD_ASSISTANCE, FLOOD)"},"entities":{"additionalProperties":true,"type":"object","title":"Entities","description":"Extracted entities map"},"entity_provenance":{"additionalProperties":{"$ref":"#/components/schemas/EntityProvenance"},"type":"object","title":"Entity Provenance","description":"Provenance tracking for extracted entities"},"temporal_context":{"additionalProperties":true,"type":"object","title":"Temporal Context","description":"Resolved date and time period"},"jurisdiction":{"additionalProperties":true,"type":"object","title":"Jurisdiction","description":"Country, state, and region context"},"conversation_context_used":{"additionalProperties":true,"type":"object","title":"Conversation Context Used","description":"Context inheritance decision record"},"missing_information":{"items":{"$ref":"#/components/schemas/MissingInfoItem"},"type":"array","title":"Missing Information","description":"Missing items requiring clarification"},"action_required":{"type":"string","title":"Action Required","description":"Action decision (e.g. FETCH_WEATHER, SEARCH_KNOWLEDGE_BASE, ASK_CLARIFICATION)","default":"GENERATE_RESPONSE"},"selected_tool":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Tool","description":"Selected tool identifier"},"tool_arguments":{"additionalProperties":true,"type":"object","title":"Tool Arguments","description":"Validated parameters sent to tool"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Decision confidence score","default":1.0},"validation_status":{"type":"string","title":"Validation Status","description":"Tool result validation status: PASSED, FAILED, NOT_APPLICABLE","default":"PASSED"}},"type":"object","required":["intent"],"title":"ConversationDecision"},"DocumentItem":{"properties":{"document_name":{"type":"string","title":"Document Name","description":"Official title of document"},"purpose":{"type":"string","title":"Purpose","description":"Why this document is required"},"how_to_obtain":{"type":"string","title":"How To Obtain","description":"Step-by-step guidance on acquiring the document"},"is_mandatory":{"type":"boolean","title":"Is Mandatory","description":"Whether application fails without it","default":true}},"type":"object","required":["document_name","purpose","how_to_obtain"],"title":"DocumentItem"},"EligibilityItem":{"properties":{"scheme_id":{"type":"string","title":"Scheme Id","description":"Target scheme identifier"},"status":{"$ref":"#/components/schemas/EligibilityStatus","description":"Evaluated eligibility status"},"matching_criteria":{"items":{"type":"string"},"type":"array","title":"Matching Criteria","description":"Criteria satisfied by user facts"},"unmet_criteria":{"items":{"type":"string"},"type":"array","title":"Unmet Criteria","description":"Criteria failed or unsatisfied"},"reasoning":{"type":"string","title":"Reasoning","description":"Deterministic explanation of evaluation result"}},"type":"object","required":["scheme_id","status","reasoning"],"title":"EligibilityItem"},"EligibilityStatus":{"type":"string","enum":["LIKELY_ELIGIBLE","POTENTIALLY_ELIGIBLE","INELIGIBLE","UNCERTAIN"],"title":"EligibilityStatus"},"EntityProvenance":{"type":"string","enum":["current_message","conversation_context","tool_result","system_default"],"title":"EntityProvenance"},"EvidenceItem":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"scheme_id":{"type":"string","title":"Scheme Id"},"title":{"type":"string","title":"Title"},"section_type":{"type":"string","title":"Section Type","default":"OVERVIEW"},"content":{"type":"string","title":"Content"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","default":"IN"},"jurisdiction_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction Level","default":"NATIONAL"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"source_url":{"type":"string","title":"Source Url","description":"Verified direct government portal URL"},"issuing_authority":{"type":"string","title":"Issuing Authority","description":"Official government department"},"similarity_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Similarity Score","description":"Cosine similarity score"},"last_verified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Verified","description":"Verification date"}},"type":"object","required":["chunk_id","scheme_id","title","content","source_url","issuing_authority","similarity_score"],"title":"EvidenceItem"},"FlowType":{"type":"string","enum":["CRISIS","PUBLIC_SERVICE","ELIGIBILITY_CHECK","DOCUMENT_GUIDANCE","GENERAL_INFORMATION","WEB_SEARCH_REQUIRED","AMBIGUOUS"],"title":"FlowType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MissingInfoItem":{"properties":{"field":{"type":"string","title":"Field","description":"Key identifier for missing attribute"},"question":{"type":"string","title":"Question","description":"User-facing prompt question to clarify the missing fact"},"importance":{"type":"string","title":"Importance","description":"Priority level: high, medium, low","default":"high"}},"type":"object","required":["field","question"],"title":"MissingInfoItem"},"RecommendationItem":{"properties":{"scheme_id":{"type":"string","title":"Scheme Id","description":"Unique scheme identifier"},"title":{"type":"string","title":"Title","description":"Name of public service / assistance program"},"issuing_authority":{"type":"string","title":"Issuing Authority","description":"Official government department or agency"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","default":"IN"},"jurisdiction_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction Level","default":"NATIONAL"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"category":{"type":"string","title":"Category","description":"Service domain / category"},"summary":{"type":"string","title":"Summary","description":"Concise explanation of assistance provided"},"match_confidence":{"type":"string","title":"Match Confidence","description":"Confidence level: HIGH, MEDIUM, LOW","default":"HIGH"}},"type":"object","required":["scheme_id","title","issuing_authority","category","summary"],"title":"RecommendationItem"},"SahayResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"Unique UUID for tracing request"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO 8601 timestamp"},"flow":{"$ref":"#/components/schemas/FlowType","description":"Detected workflow route"},"situation":{"$ref":"#/components/schemas/Situation","description":"Extracted situation details"},"urgency":{"$ref":"#/components/schemas/Urgency","description":"Urgency assessment"},"missing_information":{"items":{"$ref":"#/components/schemas/MissingInfoItem"},"type":"array","title":"Missing Information","description":"Clarification items needed"},"recommendations":{"items":{"$ref":"#/components/schemas/RecommendationItem"},"type":"array","title":"Recommendations","description":"Matching assistance programs"},"eligibility":{"items":{"$ref":"#/components/schemas/EligibilityItem"},"type":"array","title":"Eligibility","description":"Evaluated eligibility rules"},"documents":{"items":{"$ref":"#/components/schemas/DocumentItem"},"type":"array","title":"Documents","description":"Required documents checklist"},"action_plan":{"items":{"$ref":"#/components/schemas/ActionStep"},"type":"array","title":"Action Plan","description":"Ordered step-by-step next steps"},"sources":{"items":{"$ref":"#/components/schemas/SourceItem"},"type":"array","title":"Sources","description":"Verified authoritative evidence links"},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceItem"},"type":"array","title":"Evidence","description":"Retrieved RAG evidence chunks"},"disclaimer":{"type":"string","title":"Disclaimer","description":"Non-hallucinatory legal disclaimer","default":"DISCLAIMER: Sahay is an independent public-service navigator and does not guarantee official legal eligibility. Please verify all requirements directly with the issuing government authority."},"decision_metadata":{"anyOf":[{"$ref":"#/components/schemas/ConversationDecision"},{"type":"null"}],"description":"Inspectable structured decision metadata (Debug Observability)"}},"type":"object","required":["request_id","timestamp","flow","situation","urgency"],"title":"SahayResponse"},"Situation":{"properties":{"summary":{"type":"string","title":"Summary","description":"Brief natural language summary of detected context"},"extracted_facts":{"additionalProperties":true,"type":"object","title":"Extracted Facts","description":"Facts extracted from input (income, employment, location, etc.)"},"primary_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Intent","description":"Classified primary intent taxonomy"},"weather_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Weather Data","description":"Live weather payload from Open-Meteo"}},"type":"object","required":["summary"],"title":"Situation"},"SourceItem":{"properties":{"title":{"type":"string","title":"Title","description":"Title of official source or portal"},"url":{"type":"string","title":"Url","description":"Verified direct web link"},"issuing_authority":{"type":"string","title":"Issuing Authority","description":"Official issuing authority"},"last_verified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Verified","description":"ISO date when link was verified"}},"type":"object","required":["title","url","issuing_authority"],"title":"SourceItem"},"TTEApproveRequest":{"properties":{"proposal_id":{"type":"string","title":"Proposal Id"},"approved_by":{"type":"string","title":"Approved By","default":"ADMIN"}},"type":"object","required":["proposal_id"],"title":"TTEApproveRequest"},"TTEProposal":{"properties":{"proposal_id":{"type":"string","title":"Proposal Id"},"tool_name":{"type":"string","title":"Tool Name"},"problem_context":{"type":"string","title":"Problem Context"},"generated_code":{"type":"string","title":"Generated Code"},"test_results":{"additionalProperties":true,"type":"object","title":"Test Results"},"static_analysis_passed":{"type":"boolean","title":"Static Analysis Passed","default":false},"security_audit_passed":{"type":"boolean","title":"Security Audit Passed","default":false},"status":{"$ref":"#/components/schemas/TTEProposalStatus","default":"PROPOSED"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["proposal_id","tool_name","problem_context","generated_code","created_at"],"title":"TTEProposal"},"TTEProposalStatus":{"type":"string","enum":["PROPOSED","VALIDATED","APPROVED","REJECTED"],"title":"TTEProposalStatus"},"ToolDefinition":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"category":{"type":"string","title":"Category"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"output_schema":{"additionalProperties":true,"type":"object","title":"Output Schema"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"reliability_score":{"type":"number","title":"Reliability Score","default":1.0},"status":{"type":"string","title":"Status","default":"ACTIVE"},"created_at":{"type":"string","title":"Created At"},"approved_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approved By"}},"type":"object","required":["name","version","category","description","input_schema","output_schema","permissions","created_at"],"title":"ToolDefinition"},"Urgency":{"properties":{"level":{"$ref":"#/components/schemas/UrgencyLevel","description":"Assessed urgency rating"},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","description":"Confidence/severity score between 0.0 and 1.0"},"reasoning":{"type":"string","title":"Reasoning","description":"Justification for the urgency rating"}},"type":"object","required":["level","score","reasoning"],"title":"Urgency"},"UrgencyLevel":{"type":"string","enum":["CRISIS","HIGH","NORMAL","INFORMATIONAL"],"title":"UrgencyLevel"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}