{"openapi":"3.0.3","info":{"title":"SongHuo EN API","version":"0.2.0","description":"Pain description → muscle identification → exercise prescription. A 3-step conversational API for AI agents. Built by JiuCheng XiaoFang · JinDianJiu pain relief team. 58 muscles, 6 body regions, evidence-based self-tests and exercise protocols.","contact":{"name":"JiuCheng XiaoFang","url":"https://songhuo-api.com"},"x-logo":{"url":"https://songhuo-api.com/logo.png","altText":"SongHuo API"},"x-use-cases":["AI health assistant agents that help users identify muscle pain","Fitness apps providing targeted exercise prescriptions","Telehealth triage — guide patients to relevant self-tests","Physical therapy platforms — automated initial assessment","Wellness chatbots — answer 'why does my X hurt?' questions"]},"servers":[{"url":"https://songhuo-api.com","description":"Production"}],"paths":{"/api/en":{"get":{"operationId":"getApiInfo","summary":"Get API information","description":"Returns API metadata: name, version, available endpoints, pricing, and muscle count.","tags":["Info"],"responses":{"200":{"description":"API information","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"SongHuo EN API"},"version":{"type":"string","example":"0.2"},"description":{"type":"string"},"muscles":{"type":"integer","example":58},"regions":{"type":"array","items":{"type":"string"},"example":["headNeck","shoulder","upperArm","chestBack","lumbar","lowerLimb"]},"pricing":{"type":"string","example":"Free during beta"}}}}}}}}},"/api/en/pain":{"post":{"operationId":"painConversation","summary":"3-step pain-to-exercise conversation","description":"A conversational API that identifies the muscle causing pain and returns a targeted exercise prescription. Call in sequence: Step 1 (describe pain) → Step 2 (get self-tests) → Step 3 (report test result → get exercise).","tags":["Pain Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"step":{"type":"integer","description":"Conversation step: 1, 2, or 3","example":1},"pain":{"type":"string","description":"Step 1: Natural language pain description","example":"My knee hurts going down stairs"},"region":{"type":"string","description":"Step 2 & 3: Body region from step 1 response","example":"lowerLimb"},"testResult":{"type":"string","description":"Step 3: Results of self-tests from step 2","example":"Front of knee hurts during wall sit test"}}},"examples":{"step1":{"summary":"Step 1 — Describe pain","value":{"step":1,"pain":"My shoulder hurts when I lift my arm"}},"step2":{"summary":"Step 2 — Request self-tests","value":{"step":2,"region":"shoulder"}},"step3":{"summary":"Step 3 — Report test results","value":{"step":3,"region":"shoulder","testResult":"Pain on empty can test, outer shoulder"}}}}}},"responses":{"200":{"description":"Conversation response — varies by step","content":{"application/json":{"schema":{"oneOf":[{"description":"Step 1 response","type":"object","properties":{"step":{"type":"integer","example":1},"region":{"type":"string","example":"lowerLimb"},"question":{"type":"string","example":"Is the pain in the front of the knee, back of the knee, thigh, calf, or foot?"}}},{"description":"Step 2 response","type":"object","properties":{"step":{"type":"integer","example":2},"tests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"confirm":{"type":"string"}}}},"question":{"type":"string"}}},{"description":"Step 3 response — matched muscle and exercise","type":"object","properties":{"step":{"type":"integer","example":3},"result":{"type":"object","properties":{"muscle":{"type":"string","example":"Quadriceps"},"function":{"type":"string","example":"Extends knee, stabilizes kneecap"},"exercise":{"type":"object","properties":{"name":{"type":"string"},"how":{"type":"string"},"sets":{"type":"string"},"frequency":{"type":"string"}}},"precautions":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string","enum":["high","medium"]}}}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/en/muscles":{"get":{"operationId":"listMuscles","summary":"List all muscles","description":"Returns a flat list of all 58 muscles with id, name, and region. Use /api/en/muscles/{id} for full details.","tags":["Reference"],"responses":{"200":{"description":"Muscle list","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"E-M01"},"muscle":{"type":"string","example":"Quadriceps"},"region":{"type":"string","example":"Leg/Knee"}}}}}}}}}},"/api/en/muscles/{muscleId}":{"get":{"operationId":"getMuscleDetail","summary":"Get full muscle details","description":"Returns complete muscle data including function, pain pattern, self-test, exercise, and precautions.","tags":["Reference"],"parameters":[{"name":"muscleId","in":"path","required":true,"schema":{"type":"string"},"description":"Muscle ID (e.g., E-M01, S-M02, L-M01)","example":"E-M01"}],"responses":{"200":{"description":"Full muscle data","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"muscle":{"type":"string"},"region":{"type":"string"},"function":{"type":"string"},"pain_pattern":{"type":"string"},"how_to_confirm":{"type":"string"},"best_exercise":{"type":"object"},"life_precautions":{"type":"array","items":{"type":"string"}}}}}}},"404":{"description":"Muscle not found"}}}},"/api/en/subscribe":{"get":{"operationId":"getSubscriptionInfo","summary":"Pricing and subscription info","tags":["Info"],"responses":{"200":{"description":"Subscription information","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string","example":"free"},"plan":{"type":"string"},"future-pricing":{"type":"string","example":"After beta: $0.01-0.10 per 1,000 requests"}}}}}}}}}},"tags":[{"name":"Info","description":"API metadata and pricing"},{"name":"Pain Analysis","description":"3-step pain-to-exercise conversation"},{"name":"Reference","description":"Muscle database lookup"}],"x-ai-agent-instructions":{"description":"How AI agents should use this API","conversation_flow":["1. User describes their pain in natural language (e.g., 'my knee hurts going down stairs')","2. POST to /api/en/pain with {step:1, pain: userDescription}","3. API returns {region, question} — present the question to the user","4. POST to /api/en/pain with {step:2, region: regionFromStep1}","5. API returns {tests, question} — present the 3 self-tests to the user","6. User performs one or more tests and reports results","7. POST to /api/en/pain with {step:3, region, testResult: userReport}","8. API returns {result: {muscle, function, exercise, precautions, confidence}}","9. Present the exercise and precautions to the user in a helpful format"],"disclaimer":"This API provides exercise suggestions based on muscle pain patterns. It is NOT a medical diagnosis. Always advise users to consult a healthcare professional for persistent or severe pain."}}