{"openapi":"3.0.3","info":{"title":"CaraLoom Discharge API","version":"v1","description":"Search the verified clinical workforce, submit one-click discharge referrals, and resolve geography. Sandbox keys return de-identified demo data; production keys write real referrals into the live pipeline and emit signed webhooks. Authenticate with `Authorization: Bearer <key>` or `X-API-Key`.","contact":{"name":"CaraLoom","url":"https://healthy-connect-test.emergent.host/developers"}},"servers":[{"url":"https://healthy-connect-test.emergent.host/api","description":"Sandbox + production"}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"tags":[{"name":"Clinicians"},{"name":"Referrals"},{"name":"Geo"},{"name":"Webhooks"},{"name":"System"}],"paths":{"/v1/health":{"get":{"tags":["System"],"summary":"Liveness probe","security":[],"responses":{"200":{"description":"OK"}}}},"/v1/clinicians/search":{"get":{"tags":["Clinicians"],"summary":"Search verified clinicians","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"example":"TX"},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"zip","in":"query","schema":{"type":"string"},"example":"78701"},{"name":"diagnosis","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Matching clinicians","content":{"application/json":{"schema":{"type":"object","properties":{"env":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"snd_1a2b3c4d"},"display_name":{"type":"string"},"specialties":{"type":"array","items":{"type":"string"}},"license_type":{"type":"string","example":"RN"},"city":{"type":"string"},"state":{"type":"string"},"hourly_rate":{"type":"number"},"rating":{"type":"number"},"available_now":{"type":"boolean"},"telehealth":{"type":"boolean"}}}},"rate":{"type":"object","properties":{"rpm_limit":{"type":"integer"},"rpm_remaining":{"type":"integer"},"rpd_limit":{"type":"integer"},"rpd_remaining":{"type":"integer"}}},"ai_safety_posture":{"type":"object","description":"Compact AI-safety-posture envelope returned on every Discharge API response that involves a clinical recommendation. Lists the AI clinical surfaces that influenced the response, their current clinician-validation state, the active platform-wide guardrails (BAA chain, PHI scrub, audit log, clinician-in-the-loop), and a `posture_url` deep link to the human-readable transparency page. Hospital procurement teams pull this for vendor diligence.","properties":{"version":{"type":"string","example":"1.0"},"baa_chain_active":{"type":"boolean","example":true},"summary":{"type":"object","properties":{"total":{"type":"integer","example":7},"validated":{"type":"integer","example":0},"refresh_due":{"type":"integer","example":0},"pending":{"type":"integer","example":7}}},"platform_guardrails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"touched_surfaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"patient.intake_assessment"},"name":{"type":"string","example":"Patient Intake Assessment"},"risk_class":{"type":"string","enum":["low","medium","high"],"example":"high"},"endpoint":{"type":"string"},"model":{"type":"string","example":"Vertex AI · Gemini 2.5 Flash"},"validation":{"type":"object","properties":{"state":{"type":"string","enum":["signed","refresh_due","pending"]},"reviewer":{"type":"string","nullable":true},"credentials":{"type":"array","items":{"type":"string"}},"npi":{"type":"string","nullable":true},"signed_at":{"type":"string","format":"date","nullable":true},"expires_at":{"type":"string","format":"date","nullable":true},"cases_reviewed":{"type":"integer","nullable":true},"pass_rate":{"type":"number","nullable":true}}}}}},"posture_url":{"type":"string","example":"/ai-safety"},"generated_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited"}}}},"/v1/discharge-referrals":{"post":{"tags":["Referrals"],"summary":"Submit a discharge referral","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DischargeReferral"}}}},"responses":{"200":{"description":"Referral created + matched clinicians","content":{"application/json":{"schema":{"type":"object","properties":{"env":{"type":"string"},"referral_id":{"type":"string"},"status":{"type":"string"},"live":{"type":"boolean"},"matched_clinicians":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"snd_1a2b3c4d"},"display_name":{"type":"string"},"specialties":{"type":"array","items":{"type":"string"}},"license_type":{"type":"string","example":"RN"},"city":{"type":"string"},"state":{"type":"string"},"hourly_rate":{"type":"number"},"rating":{"type":"number"},"available_now":{"type":"boolean"},"telehealth":{"type":"boolean"}}}},"ai_safety_posture":{"type":"object","description":"Compact AI-safety-posture envelope returned on every Discharge API response that involves a clinical recommendation. Lists the AI clinical surfaces that influenced the response, their current clinician-validation state, the active platform-wide guardrails (BAA chain, PHI scrub, audit log, clinician-in-the-loop), and a `posture_url` deep link to the human-readable transparency page. Hospital procurement teams pull this for vendor diligence.","properties":{"version":{"type":"string","example":"1.0"},"baa_chain_active":{"type":"boolean","example":true},"summary":{"type":"object","properties":{"total":{"type":"integer","example":7},"validated":{"type":"integer","example":0},"refresh_due":{"type":"integer","example":0},"pending":{"type":"integer","example":7}}},"platform_guardrails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"touched_surfaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"patient.intake_assessment"},"name":{"type":"string","example":"Patient Intake Assessment"},"risk_class":{"type":"string","enum":["low","medium","high"],"example":"high"},"endpoint":{"type":"string"},"model":{"type":"string","example":"Vertex AI · Gemini 2.5 Flash"},"validation":{"type":"object","properties":{"state":{"type":"string","enum":["signed","refresh_due","pending"]},"reviewer":{"type":"string","nullable":true},"credentials":{"type":"array","items":{"type":"string"}},"npi":{"type":"string","nullable":true},"signed_at":{"type":"string","format":"date","nullable":true},"expires_at":{"type":"string","format":"date","nullable":true},"cases_reviewed":{"type":"integer","nullable":true},"pass_rate":{"type":"number","nullable":true}}}}}},"posture_url":{"type":"string","example":"/ai-safety"},"generated_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Missing/invalid key"},"429":{"description":"Rate limited"}}}},"/v1/geo/zip/{zip}":{"get":{"tags":["Geo"],"summary":"Resolve a ZIP to city + state","parameters":[{"name":"zip","in":"path","required":true,"schema":{"type":"string"},"example":"78701"}],"responses":{"200":{"description":"Resolved geography"},"404":{"description":"Unknown ZIP"}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"Get registered webhook","responses":{"200":{"description":"Webhook config"}}},"post":{"tags":["Webhooks"],"summary":"Register/replace webhook (returns signing secret once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegister"}}}},"responses":{"200":{"description":"Registered"}}},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","responses":{"200":{"description":"Deleted"}}}},"/v1/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Send a test `ping` event","responses":{"200":{"description":"Sent"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"DischargeReferral":{"type":"object","required":["primary_diagnosis"],"properties":{"patient_initials":{"type":"string","example":"R.K."},"primary_diagnosis":{"type":"string","example":"CHF"},"care_type":{"type":"string","example":"Skilled Nursing"},"state":{"type":"string","example":"TX"},"zip":{"type":"string","example":"78701"},"notes":{"type":"string"}}},"WebhookRegister":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https://your-app.com/hooks"},"events":{"type":"array","items":{"type":"string","enum":["referral.created","referral.matched","ping"]}}}},"Clinician":{"type":"object","properties":{"id":{"type":"string","example":"snd_1a2b3c4d"},"display_name":{"type":"string"},"specialties":{"type":"array","items":{"type":"string"}},"license_type":{"type":"string","example":"RN"},"city":{"type":"string"},"state":{"type":"string"},"hourly_rate":{"type":"number"},"rating":{"type":"number"},"available_now":{"type":"boolean"},"telehealth":{"type":"boolean"}}}}}}