{ "openapi": "3.1.0", "info": { "title": "Khulna Doctors Hub (KDH) Healthcare Data Cloud API", "version": "1.0.0", "description": "Official B2B Developer & AI Agent API for Khulna Division, Bangladesh. Provides real-time verified doctors (BMDC validated), DGHS-accredited hospital facilities, diagnostic price benchmarking, and Model Context Protocol (MCP) tool calling.", "contact": { "name": "KDH Developer Support", "email": "api@khulnadoctorshub.com", "url": "https://khulnadoctorshub.com" } }, "servers": [ { "url": "https://doctorshubapi.anikchowdhury.workers.dev", "description": "Active Cloudflare Edge Server" }, { "url": "https://api.khulnadoctorshub.com", "description": "Canonical Production Edge API" }, { "url": "https://doctorshubapi.anikchowdhury.workers.dev", "description": "Direct Edge Origin Fallback" } ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/v1/doctors": { "get": { "summary": "Search & Filter Verified Doctors", "description": "Discover physicians by clinical specialty, district, name, or BMDC verification status.", "parameters": [ { "name": "query", "in": "query", "description": "Search by name, degrees, or slug", "schema": { "type": "string" } }, { "name": "district", "in": "query", "description": "One of 10 districts in Khulna Division", "schema": { "type": "string" } }, { "name": "specialization", "in": "query", "description": "e.g., Cardiology, Pediatrics, Gynecology", "schema": { "type": "string" } }, { "name": "bmdc_verified", "in": "query", "description": "Filter only BMDC verified doctors", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of doctors" }, "401": { "description": "Unauthorized or invalid API key" }, "429": { "description": "Rate limit or monthly quota exceeded" } } } }, "/v1/doctors/{id_or_slug}": { "get": { "summary": "Get Doctor Profile & Chamber Schedules", "parameters": [ { "name": "id_or_slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full doctor profile, bio, fees, and chamber schedules" }, "404": { "description": "Doctor not found" } } } }, "/v1/doctors/verify/{bmdc_number}": { "get": { "summary": "Instant BMDC Registration Verification", "description": "Validate a physician's license for insurance, corporate compliance, and medical verification.", "parameters": [ { "name": "bmdc_number", "in": "path", "required": true, "description": "e.g. A-15960", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification status and authentic practitioner details" } } } }, "/v1/facilities": { "get": { "summary": "Search DGHS-Verified Facilities", "description": "Query hospitals, clinics, diagnostic centers, dental clinics, and blood banks.", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "district", "in": "query", "schema": { "type": "string" } }, { "name": "upazila", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "hospital", "clinic", "diagnostic_lab", "dental", "blood_bank" ] } }, { "name": "emergency", "in": "query", "schema": { "type": "boolean" } }, { "name": "dghs_verified", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Paginated list of healthcare facilities with DGHS codes" } } } }, "/v1/facilities/nearby": { "get": { "summary": "Nearby Geospatial Hospital Search", "description": "Haversine edge calculation to locate open facilities within a given kilometer radius.", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "radius_km", "in": "query", "schema": { "type": "number", "default": 10 } }, { "name": "emergency_only", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Sorted list of nearest facilities with distance" } } } }, "/v1/tests/compare": { "get": { "summary": "Diagnostic Test Price Benchmarking", "description": "Compare fee ceilings across 1,539 labs for standardized diagnostic tests.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "district", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Price benchmark statistics and participating lab price cards" } } } }, "/v1/tools": { "get": { "operationId": "listAvailableTools", "summary": "List Autonomous AI Agent Tools", "description": "Returns JSON schema definitions for all 7 autonomous healthcare tools formatted for OpenAI, MCP, or Gemini.", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "openai", "mcp", "catalog" ], "default": "catalog" } } ], "responses": { "200": { "description": "Array of available tool definitions with JSON schemas" } } } }, "/v1/tools/call": { "post": { "operationId": "executeAgentTool", "summary": "Execute AI Agent Tool (Unified Router)", "description": "Execute any registered autonomous tool with validation, rate limits, and write-ahead audit logs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "description": "Name of target tool" }, "parameters": { "type": "object", "description": "Input parameters matching tool schema" } }, "required": [ "tool" ] } } } }, "responses": { "200": { "description": "Tool execution result with audit telemetry" }, "400": { "description": "Schema validation failure" }, "403": { "description": "Insufficient tool permissions" } } } }, "/v1/tools/search_doctors": { "post": { "operationId": "searchDoctors", "summary": "Search Verified Doctors (Agent Tool)", "description": "Discover verified doctors across 10 districts in Khulna Division by specialty, district, or symptoms. Returns chamber locations, visiting hours (সময়সূচী), and consultation fees.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "specialty": { "type": "string", "description": "e.g. Cardiology, Pediatrics, Gynecology" }, "district": { "type": "string", "description": "One of 10 districts in Khulna Division" }, "upazila": { "type": "string", "description": "Upazila or area name" }, "query": { "type": "string", "description": "Name or symptoms" }, "bmdc_verified_only": { "type": "boolean" }, "limit": { "type": "integer", "default": 10, "maximum": 50 } } } } } }, "responses": { "200": { "description": "List of matched verified doctors with chamber locations, visiting hours (সময়সূচী), and consultation fees" } } } }, "/v1/tools/verify_doctor_bmdc": { "post": { "operationId": "verifyDoctorBmdc", "summary": "Verify Physician BMDC License (Agent Tool)", "description": "Audit official Bangladesh Medical & Dental Council license number to prevent medical impersonation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bmdc_number": { "type": "string", "description": "e.g. A-15960" } }, "required": [ "bmdc_number" ] } } } }, "responses": { "200": { "description": "Official BMDC verification record" } } } }, "/v1/tools/find_emergency_hospital": { "post": { "operationId": "findEmergencyHospital", "summary": "Locate 24/7 Emergency ICU Hospitals (Agent Tool)", "description": "Find nearest 24/7 emergency facilities with ICU beds. Strictly complies with zero helpline leak standards.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "district": { "type": "string", "description": "One of 10 districts in Khulna Division" }, "requires_icu": { "type": "boolean" }, "emergency_only": { "type": "boolean", "default": true } }, "required": [ "district" ] } } } }, "responses": { "200": { "description": "Emergency hospital emergency contacts and capabilities" } } } }, "/v1/tools/compare_diagnostic_tests": { "post": { "operationId": "compareDiagnosticTests", "summary": "Compare Diagnostic Lab Test Prices (Agent Tool)", "description": "Benchmark test prices across accredited diagnostic laboratories in Khulna Division.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "test_name": { "type": "string", "description": "e.g. Lipid Profile, CBC, MRI Brain" }, "district": { "type": "string" } }, "required": [ "test_name" ] } } } }, "responses": { "200": { "description": "Fee comparison and price breakdown" } } } }, "/v1/tools/book_patient_appointment": { "post": { "operationId": "bookPatientAppointment", "summary": "Book Patient Appointment Pass (Agent Action Tool)", "description": "Book an appointment serial with verified doctor. Emits 380px digital patient pass and triggers notification workflows.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "doctorId": { "type": "integer", "description": "Doctor ID" }, "patientName": { "type": "string", "description": "Patient full name" }, "patientPhone": { "type": "string", "description": "11-digit BD mobile (e.g. 01712345678)" }, "appointmentDate": { "type": "string", "description": "YYYY-MM-DD (up to 30 days ahead)" }, "hospitalId": { "type": "integer", "description": "Optional specific chamber ID" }, "notes": { "type": "string", "description": "Chief complaints or symptoms" }, "idempotency_key": { "type": "string", "description": "UUID to prevent double booking" } }, "required": [ "doctorId", "patientName", "patientPhone", "appointmentDate" ] } } } }, "responses": { "200": { "description": "Booked serial number, 380px digital pass URL, and WhatsApp link" } } } }, "/v1/tools/lookup_patient_pass": { "post": { "operationId": "lookupPatientPass", "summary": "Lookup Digital Appointment Pass (Agent Tool)", "description": "Retrieve verified 380px digital pass details, status, chamber directions, and QR link.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passCode": { "type": "string", "description": "Appointment serial number or token" } }, "required": [ "passCode" ] } } } }, "responses": { "200": { "description": "Appointment pass details with masked phone" } } } }, "/v1/tools/dispatch_whatsapp_confirmation": { "post": { "operationId": "dispatchWhatsappConfirmation", "summary": "Dispatch WhatsApp Pass Notification (Agent Action Tool)", "description": "Send official bilingual WhatsApp pass to patient or chamber desk.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passCode": { "type": "string", "description": "Appointment serial number" }, "recipientType": { "type": "string", "enum": [ "patient", "chamber" ], "default": "patient" }, "customNote": { "type": "string" } }, "required": [ "passCode" ] } } } }, "responses": { "200": { "description": "Delivery status and prefilled wa.me share link" } } } }, "/v1/mcp": { "post": { "summary": "Model Context Protocol (MCP) JSON-RPC Endpoint", "description": "AI Agent native tool calling interface supporting tools/list and tools/call.", "responses": { "200": { "description": "MCP JSON-RPC response" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "kdh_live_..." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } } }