{ "openapi": "3.1.0", "info": { "title": "SeniorPulse API", "description": "Global elder care intelligence API. AI-synthesized Medicare guidance, care facility evaluation, medication safety, benefits discovery, and caregiver support for seniors and their families worldwide. US endpoints cover Medicare, SSI, Medicaid, VA benefits, SNAP, and LIHEAP. Global endpoints cover medication safety, memory care, grief support, and elder law applicable in any jurisdiction. All endpoints return structured JSON and require x402 micropayment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.", "version": "1.2.0", "contact": { "url": "https://seniorpulse.vercel.app" } }, "servers": [ { "url": "https://seniorpulse.vercel.app" } ], "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 payment signature (USDC on Base mainnet). Send a GET request without this header to receive a 402 Payment Required response containing payment details in the PAYMENT-REQUIRED header. Sign the payment and retry with the signature.", "required": true } } }, "security": [ { "x402": [] } ], "paths": { "/api/senior/medicare": { "get": { "summary": "Medicare plan guidance", "description": "Synthesizes Medicare options for any enrollment situation. Compares Original Medicare vs. Medicare Advantage, explains Medigap supplement options, covers Part D drug plan selection, and provides critical enrollment deadline warnings. Supports turning-65, disability enrollment, losing employer coverage, and annual plan-switching scenarios. US-specific.", "operationId": "seniorMedicare", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorBenefits to check Medicare Savings Program eligibility; follow with seniorMeds to evaluate drug plan coverage for specific medications", "parameters": [ { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ZIP code for plan availability context (US)" }, { "name": "situation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Enrollment scenario — e.g. 'turning 65', 'comparing plans', 'losing employer coverage at 67', 'enrolling due to disability', 'reviewing Part D'" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language (e.g. 'es', 'zh', 'ko', 'vi', 'tl') — Claude responds natively in any language" } ], "responses": { "200": { "description": "Medicare plan analysis with recommendation and next steps" }, "402": { "description": "Payment required — see PAYMENT-REQUIRED header for x402 payment details" } } } }, "/api/senior/facility": { "get": { "summary": "Care facility evaluation guide", "description": "Helps families evaluate senior care facilities by type anywhere in the world. For US queries: covers cost ranges, Medicare/Medicaid coverage, CMS star ratings, evaluation checklist, red flags, and questions to ask. For international queries: covers equivalent local care standards, funding mechanisms, and how to find regulated facilities. Returns affiliate links to A Place for Mom (US) or equivalent country-specific directories.", "operationId": "seniorFacility", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Call with nh-compare for head-to-head facility quality data; follow with seniorBenefits to check Medicaid long-term care coverage; follow with seniorLegal for POA documents needed before placement", "parameters": [ { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "City and state/country (e.g. 'Austin TX', 'London UK', 'Toronto Canada', 'Sydney Australia')" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["assisted-living", "memory-care", "skilled-nursing", "independent-living", "home-care"] }, "description": "Facility type. Defaults to assisted-living." }, { "name": "budget", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly budget in local currency (USD for US, GBP for UK, AUD for Australia, CAD for Canada)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Facility evaluation guide with cost ranges, checklist, red flags, and placement resources" }, "402": { "description": "Payment required" } } } }, "/api/senior/meds": { "get": { "summary": "Medication safety check for elderly patients (polypharmacy)", "description": "Reviews a medication list for geriatric safety using FDA drug label data and the Beers Criteria — the definitive list of medications that are inappropriate or risky for adults over 65. Flags dangerous drug interactions, geriatric dosing concerns, and black box warnings. Applicable globally — FDA drug database covers most medications sold internationally under different brand names.", "operationId": "seniorMeds", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorRxAssist if Beers Criteria medications are flagged to find safer alternatives or cost-reduction programs; chain with seniorBenefits if drug costs are a concern", "parameters": [ { "name": "medications", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated medication list using generic names (e.g. 'metformin,lisinopril,aspirin,diphenhydramine,amlodipine')" }, { "name": "age", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Patient age — used to calibrate Beers Criteria thresholds (most critical for ages 65–75 vs. 85+)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Medication safety review with Beers Criteria flags, interaction warnings, and consultation recommendations" }, "402": { "description": "Payment required" } } } }, "/api/senior/benefits": { "get": { "summary": "Benefits eligibility assessment (US)", "description": "Assesses eligibility for US federal and state senior benefits programs including SSI, Medicaid, Medicare Savings Programs (QMB, SLMB, QI), Extra Help (Part D subsidy), VA Aid & Attendance, and PACE. Uses state-specific income and asset thresholds. Surfaces programs most seniors miss — Medicare Savings Programs alone are claimed by only 50% of those eligible.", "operationId": "seniorBenefits", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorMedicare to optimize Part D plan based on Extra Help eligibility; follow with seniorVeterans if veteran flag is true; follow with seniorSnapUtility for food and energy assistance", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state name or 2-letter abbreviation (e.g. 'Texas', 'TX')" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly gross income in USD (Social Security, pension, wages)" }, { "name": "assets", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Total countable assets in USD — excludes primary home and one vehicle" }, { "name": "veteran", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true to include VA Aid & Attendance and other veteran-specific benefits in the assessment" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Benefits eligibility assessment with program summaries, estimated value, and application steps" }, "402": { "description": "Payment required" } } } }, "/api/senior/caregiver": { "get": { "summary": "Family caregiver resource guide", "description": "Generates a personalized caregiver resource guide covering: legal document checklist (POA, healthcare proxy, advance directive), respite care options, local resources by location, financial assistance for caregivers, and evidence-based burnout prevention strategies. Applicable globally — adapts legal document guidance to the jurisdiction described.", "operationId": "seniorCaregiver", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorLegal to generate specific elder law document guidance; follow with seniorFacility if the caregiver situation may need transitioning to a care facility; follow with seniorGrief if recent bereavement is involved", "parameters": [ { "name": "situation", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Description of the caregiving situation (e.g. 'caring for 85yo mother with dementia, living 200 miles away', 'husband with Parkinson's, need respite care options in Manchester UK')" }, { "name": "location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location for local resource search — city and country (e.g. 'Denver CO', 'Bristol UK', 'Vancouver Canada')" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Personalized caregiver resource guide with legal checklist, local resources, and burnout prevention" }, "402": { "description": "Payment required" } } } }, "/api/senior/grief": { "get": { "summary": "Post-loss estate and grief guide", "description": "Guides families through the immediate practical and emotional aftermath of losing a loved one. Covers: immediate estate steps (first 72 hours, first 30 days), survivor benefit claims (Social Security survivor benefit, pension, life insurance), probate basics by state, grief support resources, and cultural or religious considerations. Globally applicable with jurisdiction-specific estate guidance.", "operationId": "seniorGrief", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorLegal for POA and estate document guidance; follow with seniorBenefits to assess surviving spouse's benefit eligibility; follow with seniorMedicare for coverage review after spouse's passing", "parameters": [ { "name": "situation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Describe the situation (e.g. 'spouse passed 3 days ago, need to know what to do immediately', 'mother died 2 months ago, estate still open')" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "US state or country for jurisdiction-specific probate and estate guidance" }, { "name": "days_since", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Days since the loss — calibrates guidance to immediate (0–7 days), short-term (1–4 weeks), or ongoing estate (1–12 months) phases" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Post-loss practical guide with phased action steps, benefit claims, and grief support resources" }, "402": { "description": "Payment required" } } } }, "/api/senior/legal": { "get": { "summary": "Elder law document guide (POA, advance directive, guardianship)", "description": "Guides families through essential elder law documents: durable power of attorney, healthcare proxy, advance directive/living will, POLST forms, and guardianship proceedings. Explains what each document does, when it applies, and how urgency changes by cognitive capacity situation. Provides state-specific signing requirements for US; explains equivalent documents in UK, Canada, Australia, and EU jurisdictions.", "operationId": "seniorLegal", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Use before seniorFacility — POA is often required before a care facility can be contracted; pair with seniorMemory when cognitive decline is a factor in document urgency", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "US state or country for jurisdiction-specific document requirements" }, { "name": "situation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Describe the situation (e.g. 'parents have no POA, father showing memory decline', 'need healthcare proxy before surgery', 'sibling disputes who controls decisions')" }, { "name": "has_poa", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "false", "partial"] }, "description": "Whether an existing POA is in place — affects urgency and next steps" }, { "name": "capacity_concern", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true if there are concerns about the senior's cognitive capacity to sign legal documents — triggers guardianship guidance" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Elder law document guide with document explanations, signing requirements, and next steps" }, "402": { "description": "Payment required" } } } }, "/api/senior/memory": { "get": { "summary": "Cognitive decline staging and dementia care trajectory", "description": "Maps cognitive test scores (MMSE, MoCA, CDR) or described symptoms to a care trajectory. Explains what each stage means practically for daily living, driving, financial management, and care needs. Covers Alzheimer's, vascular dementia, Lewy body, and frontotemporal variants. Provides a 12–36 month planning horizon and when to make each major transition decision. Globally applicable.", "operationId": "seniorMemory", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorLegal — cognitive staging directly informs urgency of POA and advance directive documents; follow with seniorFacility when memory care transition is within 12 months; follow with seniorCaregiver for family support resources", "parameters": [ { "name": "mmse_score", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Mini-Mental State Examination score (0–30). 24–30 normal, 18–23 mild, 0–17 severe." }, { "name": "moca_score", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Montreal Cognitive Assessment score (0–30). Below 26 indicates possible impairment." }, { "name": "cdr_score", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Clinical Dementia Rating (0, 0.5, 1, 2, 3). 0=normal, 0.5=very mild, 1=mild, 2=moderate, 3=severe." }, { "name": "diagnosis", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Formal diagnosis if known (e.g. 'Alzheimer's', 'vascular dementia', 'Lewy body', 'MCI', 'frontotemporal')" }, { "name": "current_living", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current living situation (e.g. 'alone', 'with spouse', 'with adult children', 'assisted living')" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Cognitive staging assessment with care trajectory, planning horizon, and transition decision timing" }, "402": { "description": "Payment required" } } } }, "/api/senior/nh-compare": { "get": { "summary": "Nursing home quality comparison (CMS Care Compare data)", "description": "Compares nursing home quality using CMS Care Compare ratings — the official US federal database of nursing home inspections, staffing hours, quality measures, and overall star ratings. Returns head-to-head comparison of named facilities or top-rated facilities in a ZIP code area. Flags facilities with recent deficiencies, abuse citations, or low staffing.", "operationId": "seniorNhCompare", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Use after seniorFacility to get quality data on specific facilities identified in the evaluation; pair with seniorBenefits to confirm Medicaid coverage at the facilities being compared", "parameters": [ { "name": "facilities", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated facility names or addresses to compare head-to-head (e.g. 'Sunrise Senior Living Austin,Brookdale South Austin')" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ZIP code to find top-rated nursing homes in the area (used if no specific facilities named)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Nursing home quality comparison with star ratings, staffing hours, inspection history, and red flags" }, "402": { "description": "Payment required" } } } }, "/api/senior/property-tax": { "get": { "summary": "Senior property tax relief programs by state", "description": "Identifies senior property tax exemptions, freezes, deferrals, and circuit breaker programs that most homeowners miss. Covers all 50 US states — every state has at least one senior property tax relief program; most have multiple. Provides eligibility thresholds, application deadlines, estimated annual savings, and application instructions. Nationally, only 20–40% of eligible seniors claim these exemptions.", "operationId": "seniorPropertyTax", "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pair with seniorBenefits for a complete financial relief assessment; follow with seniorSnapUtility for additional household cost reduction programs", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state name or abbreviation (e.g. 'Texas', 'TX')" }, { "name": "age", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Homeowner age — many programs begin at 62, 65, or 70" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Annual household income in USD — required for income-tested programs" }, { "name": "home_value", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Estimated home value in USD — used to estimate annual savings" }, { "name": "veteran", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true to include veteran-specific property tax exemptions (available in every state)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Property tax relief programs with eligibility requirements, estimated savings, deadlines, and application steps" }, "402": { "description": "Payment required" } } } }, "/api/senior/rx-assist": { "get": { "summary": "Prescription assistance programs (Extra Help, state programs, pharma PAPs)", "description": "Identifies prescription drug financial assistance programs for seniors who cannot afford medications. Covers: Medicare Extra Help (LIS) subsidy worth up to $5,300/year, State Pharmaceutical Assistance Programs (SPAPs), pharmaceutical manufacturer Patient Assistance Programs (PAPs) that provide free brand-name medications, and GoodRx-type discount programs. State-specific and income-based.", "operationId": "seniorRxAssist", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Call after seniorMeds when Beers Criteria medications are identified — rx-assist can find safer cheaper alternatives; pair with seniorBenefits for complete cost-reduction analysis", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state name or abbreviation" }, { "name": "medications", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated medication list — used to identify specific manufacturer PAPs for each drug" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly income in USD — determines Extra Help eligibility (2024 limit: $1,903/month individual)" }, { "name": "on_medicare", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether the senior is enrolled in Medicare Part D — affects Extra Help vs. manufacturer PAP eligibility" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "Prescription assistance programs with eligibility, estimated savings, and application instructions" }, "402": { "description": "Payment required" } } } }, "/api/senior/snap-utility": { "get": { "summary": "Senior SNAP food assistance and LIHEAP utility assistance", "description": "Identifies SNAP (food stamps) and LIHEAP (Low Income Home Energy Assistance Program) eligibility for seniors. Seniors are the most under-enrolled SNAP demographic — only 42% of eligible seniors participate. Covers federal thresholds, state-specific expansions, the senior-only SNAP deduction for medical expenses, LIHEAP heating and cooling assistance, and utility discount programs by state.", "operationId": "seniorSnapUtility", "x-price-usd": 0.10, "x-agent-use-case": "on-demand", "x-agent-chaining": "Always pair with seniorBenefits for a complete financial relief assessment; follow with seniorPropertyTax for homeowner cost reduction", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state name or abbreviation" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly household income in USD" }, { "name": "household_size", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of people in the household — SNAP limits vary by household size" }, { "name": "own_home", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether the senior owns their home — affects LIHEAP eligibility and some SNAP asset tests" }, { "name": "medical_expenses", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly out-of-pocket medical expenses — seniors can deduct excess medical costs to qualify for SNAP" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "SNAP and LIHEAP eligibility assessment with estimated monthly benefit value and application steps" }, "402": { "description": "Payment required" } } } }, "/api/senior/veterans": { "get": { "summary": "VA Aid & Attendance and senior veteran benefits", "description": "Assesses eligibility for VA Aid & Attendance — the most underutilized major VA benefit, worth up to $2,727/month for a veteran couple. Also covers VA Pension, Survivors Pension (for surviving spouses), Housebound benefit, and how VA benefits interact with Medicaid. Most eligible veterans and surviving spouses have never heard of Aid & Attendance. Service requirements: 90+ days active duty with at least one day during wartime.", "operationId": "seniorVeterans", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with seniorBenefits to see how VA benefits interact with SSI and Medicaid eligibility; follow with seniorFacility if VA benefit will fund assisted living or memory care placement; follow with seniorLegal if POA is needed to file on behalf of veteran", "parameters": [ { "name": "veteran_age", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Veteran age" }, { "name": "care_cost", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly unreimbursed care costs in USD (home health aide, assisted living, adult day care)" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly gross income in USD (Social Security, pension, other)" }, { "name": "assets", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Total net worth in USD excluding primary home and vehicle — VA uses a $155,356 asset limit (2024)" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "State of residence — some states offer additional veteran benefits beyond federal VA" }, { "name": "surviving_spouse", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true if the applicant is a surviving spouse of a veteran — unlocks Survivors Pension and Aid & Attendance for surviving spouses" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language — any language supported" } ], "responses": { "200": { "description": "VA Aid & Attendance eligibility assessment with estimated monthly benefit, qualification criteria, and application steps" }, "402": { "description": "Payment required" } } } } } }