{ "openapi": "3.1.0", "info": { "title": "VetPulse API", "description": "US veterans benefits intelligence API. AI-synthesized guidance on VA disability compensation, Aid & Attendance pension, TDIU, claim strategy, caregiver stipends, GI Bill, state benefits, VA healthcare, and VA home loans. Surfaces the benefits most veterans never claim. All endpoints return structured JSON and require x402 micropayment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header. All endpoints support any language via ?lang= parameter. Also serves Canadian, Australian, UK and other Commonwealth nations' veterans benefits via ?lang= parameter for local context.", "version": "1.2.0", "contact": { "url": "https://vetpulse-five.vercel.app" } }, "servers": [ { "url": "https://vetpulse-five.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 with payment details in the PAYMENT-REQUIRED header. Sign the payment and retry.", "required": true } } }, "security": [ { "x402": [] } ], "paths": { "/api/vet/disability": { "get": { "summary": "VA disability rating analysis", "description": "Analyzes likely VA disability ratings per condition, applies VA combined rating math (whole-person formula), projects monthly compensation at each combined rating level ($165\u2013$3,737+/month), assesses PACT Act toxic exposure presumptive conditions (burn pits, Agent Orange, Camp Lejeune water), identifies secondary conditions worth adding, and outlines nexus letter topics. Covers all major presumptive conditions added 2022.", "operationId": "vetDisability", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with /api/vet/claim-builder to build the evidence package; follow with /api/vet/tdiu if combined rating may reach 60%+", "parameters": [ { "name": "conditions", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated medical conditions (e.g. 'tinnitus,PTSD,lumbar strain,sleep apnea')" }, { "name": "service_era", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Service era for presumptive condition assessment (e.g. 'Vietnam', 'Gulf War', 'OEF', 'OIF', 'Korea')" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "Disability rating analysis with compensation projections and claim strategy" }, "402": { "description": "Payment required \u2014 see PAYMENT-REQUIRED header for x402 payment details" } } } }, "/api/vet/aid-attendance": { "get": { "summary": "VA Aid & Attendance pension eligibility", "description": "Assesses VA Aid & Attendance pension eligibility \u2014 the most underutilized major VA benefit, worth up to $2,727/month for a veteran couple (2024 rates). Covers pension rates by family status (veteran alone, veteran + spouse, surviving spouse), net worth limit calculation ($155,356 in 2024), income calculation with medical expense deductions that significantly reduce countable income, wartime service requirement (90+ days active duty with one day during wartime period), and the 36-month asset transfer look-back rule.", "operationId": "vetAidAttendance", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pairs with SeniorPulse /api/senior/veterans for surviving spouses; follow with /api/vet/claim-builder for application strategy", "parameters": [ { "name": "age", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Veteran age" }, { "name": "needs", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Care needs description (e.g. 'requires daily assistance with bathing, dressing, and medication management')" }, { "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 one vehicle" }, { "name": "care_cost", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Monthly unreimbursed care costs in USD \u2014 deducted from income for pension calculation" }, { "name": "surviving_spouse", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true if applicant is a surviving spouse of a veteran \u2014 unlocks Survivors Pension and different Aid & Attendance rates" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "Aid & Attendance eligibility assessment with estimated monthly benefit and application steps" }, "402": { "description": "Payment required" } } } }, "/api/vet/tdiu": { "get": { "summary": "TDIU (Total Disability Individual Unemployability) eligibility", "description": "Assesses TDIU eligibility \u2014 pays at the 100% disability rate ($3,737/month in 2024) regardless of actual combined rating. Covers the schedular pathway (60%+ combined rating or one condition at 40%+), extraschedular pathway for veterans who don't meet schedular criteria, income threshold (marginal employment definition), evidence requirements, IU application process (VA Form 21-8940), and coordination with Social Security Disability (SSDI) \u2014 both can be collected simultaneously.", "operationId": "vetTdiu", "x-price-usd": 0.15, "x-agent-use-case": "on-demand", "x-agent-chaining": "Use after /api/vet/disability to assess TDIU eligibility based on identified ratings; follow with /api/vet/claim-builder for evidence strategy", "parameters": [ { "name": "rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current combined disability rating (e.g. '70' or '60')" }, { "name": "work_history", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Work history and current work status (e.g. 'cannot maintain substantially gainful employment due to PTSD and chronic pain')" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Current annual income \u2014 TDIU requires below federal poverty threshold for marginal employment (~$15,000)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "TDIU eligibility assessment with pathway analysis and application strategy" }, "402": { "description": "Payment required" } } } }, "/api/vet/claim-builder": { "get": { "summary": "VA disability claim evidence strategy", "description": "Builds a complete evidence strategy for a VA disability claim. Returns: which service treatment records (STRs) to request (eVet, VA, private), buddy statement structure and who should write them, C&P exam preparation tactics (what to say, what not to minimize), nexus letter topics and structure for private physicians, secondary conditions worth adding to increase the combined rating, and prioritized claim strategy. The highest-value VetPulse endpoint \u2014 prevents the most common claim mistakes that lead to years of delays.", "operationId": "vetClaimBuilder", "x-price-usd": 0.2, "x-agent-use-case": "on-demand", "x-agent-chaining": "Use after /api/vet/disability to build evidence for identified conditions; the output of this endpoint feeds directly into claim preparation \u2014 agents building veteran advocacy workflows should call this before any filing guidance", "parameters": [ { "name": "conditions", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated conditions to build evidence strategy for (e.g. 'PTSD,sleep apnea,hypertension,tinnitus')" }, { "name": "service_era", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Service era (e.g. 'Vietnam', 'Gulf War', 'OEF', 'OIF')" }, { "name": "current_rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current combined rating if filing a supplemental or new claim" }, { "name": "previous_denials", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Description of any previous claim denials \u2014 affects strategy (HLR vs. Board appeal vs. supplemental)" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "Evidence strategy brief with records to gather, exam prep, nexus letter topics, and secondary conditions" }, "402": { "description": "Payment required" } } } }, "/api/vet/caregiver": { "get": { "summary": "PCAFC caregiver stipend and benefits", "description": "PCAFC (Program of Comprehensive Assistance for Family Caregivers) eligibility and benefits \u2014 monthly stipend from approximately $800 to $3,300+/month based on veteran's care level and geography, plus CHAMPVA health insurance for the caregiver (free comprehensive health coverage), respite care (30 days/year), mental health services, and travel benefits. Eligible for veterans with a serious injury or illness incurred or aggravated in the line of duty.", "operationId": "vetCaregiver", "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with /api/vet/healthcare for CHAMPVA health coverage details for dependents; pairs with SeniorPulse /api/senior/caregiver for aging veteran caregiver situations", "parameters": [ { "name": "relationship", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Caregiver relationship to veteran (e.g. 'spouse', 'adult child', 'parent', 'sibling')" }, { "name": "veteran_needs", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Description of veteran's care needs (e.g. 'severe TBI requires 24hr supervision, cannot be left alone')" }, { "name": "discharge_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Approximate discharge date \u2014 PCAFC eligibility expanded in 2020 to all service eras" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "PCAFC eligibility assessment with stipend estimate, CHAMPVA details, and application steps" }, "402": { "description": "Payment required" } } } }, "/api/vet/education": { "get": { "summary": "GI Bill and education benefit comparison", "description": "Compares GI Bill chapters: Chapter 33 (Post-9/11 GI Bill \u2014 most comprehensive, covers tuition + housing + books), Chapter 30 (Montgomery \u2014 monthly stipend model), Chapter 35 (DEA \u2014 for dependents of P&T or deceased veterans), Chapter 1606 (Selected Reserve). Covers monthly housing allowance by school ZIP code, remaining entitlement calculation, Yellow Ribbon Program for expensive schools, STEM scholarship for qualifying STEM degrees, and Vocational Rehabilitation and Employment (Chapter 31) for veterans with service-connected disabilities.", "operationId": "vetEducation", "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Use before /api/vet/state-benefits to find state tuition waivers that stack with GI Bill; pairs with CareerPulse for career transition planning post-service", "parameters": [ { "name": "chapter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GI Bill chapter of interest (e.g. '33', '30', '35', '1606') \u2014 or omit for full comparison" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Military branch \u2014 affects reserve component benefit calculations" }, { "name": "school_location", "in": "query", "required": false, "schema": { "type": "string" }, "description": "School city and state \u2014 used to estimate monthly housing allowance (E-5 with dependent BAH rate)" }, { "name": "dependents", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether veteran has dependents \u2014 affects DEA transferability and some benefit calculations" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "GI Bill comparison with estimated benefits, housing allowance, and Voc Rehab analysis" }, "402": { "description": "Payment required" } } } }, "/api/vet/state-benefits": { "get": { "summary": "State-specific veteran benefits (all 50 states)", "description": "Comprehensive state veteran benefit analysis for any US state. Covers: property tax exemptions (range from $5,000 to full exemption for 100% P&T veterans \u2014 worth $3,000\u2013$15,000+/year in tax savings), tuition waivers at public universities, state employment preference points (federal and state hiring), hunting and fishing license benefits, DMV benefits (free or discounted license plates, driver license fees), burial benefits and state veterans cemeteries, state veterans homes for assisted living and nursing care, and any state-specific disability income exclusions. Most veterans claim fewer than 25% of available state benefits.", "operationId": "vetStateBenefits", "x-price-usd": 0.1, "x-agent-use-case": "on-demand", "x-agent-chaining": "Always pair with /api/vet/disability \u2014 most state benefits are enhanced for 100% or P&T ratings; follow with SeniorPulse /api/senior/property-tax for additional senior-specific property tax relief that stacks", "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state name or abbreviation (e.g. 'Texas', 'TX')" }, { "name": "disability_rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "VA disability rating percentage \u2014 many state benefits require minimum rating (e.g. '70', '100', 'P&T')" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "State veteran benefits analysis with eligibility, estimated value, and application steps" }, "402": { "description": "Payment required" } } } }, "/api/vet/healthcare": { "get": { "summary": "VA healthcare priority group and coverage analysis", "description": "Determines VA healthcare priority group placement (1\u20138) which drives copay schedules and coverage levels. Covers: CHAMPVA for dependents of P&T veterans (free comprehensive health coverage for spouse and children), Community Care Network eligibility (when to use outside VA providers), dental coverage eligibility by disability rating (100% or P&T veterans get free dental), mental health same-day services policy, and Medicare/VA coordination strategy for veterans on both.", "operationId": "vetHealthcare", "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Follow with SeniorPulse /api/senior/medicare for aging veterans coordinating VA healthcare with Medicare; pairs with SeniorPulse /api/senior/meds for medication safety review using VA formulary context", "parameters": [ { "name": "priority_group", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Current VA priority group if known (1\u20138)" }, { "name": "income", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Annual household income \u2014 affects priority group 5\u20138 placement and copay amounts" }, { "name": "disability_rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "VA disability rating \u2014 service-connected veterans (any rating) are Priority Group 1\u20133" }, { "name": "dependents", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true to include CHAMPVA coverage analysis for dependents" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "VA healthcare priority group placement with copay schedule and coverage analysis" }, "402": { "description": "Payment required" } } } }, "/api/vet/home-loan": { "get": { "summary": "VA home loan benefit analysis", "description": "Analyzes VA home loan advantages for a specific purchase scenario. Funding fee exemption for veterans with any service-connected disability rating saves $5,000\u2013$15,000 on a typical purchase. No PMI requirement saves $150\u2013$400/month vs. conventional loans. Covers COE (Certificate of Eligibility) process and entitlement restoration after prior VA loan use. Identifies state first-time buyer programs that stack with VA loan for additional down payment assistance or rate reductions.", "operationId": "vetHomeLoan", "x-price-usd": 0.08, "x-agent-use-case": "on-demand", "x-agent-chaining": "Pairs with PropPulse /api/prop/mortgage for full mortgage analysis; follow with /api/vet/state-benefits to identify state housing assistance that stacks with VA loan", "parameters": [ { "name": "disability_rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "VA disability rating \u2014 any service-connected rating eliminates funding fee (saves $5k\u2013$15k)" }, { "name": "purchase_price", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Target home purchase price in USD \u2014 used to calculate funding fee savings and PMI comparison" }, { "name": "prior_va_loan", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether veteran has used a VA loan before \u2014 triggers entitlement restoration guidance" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "State of purchase \u2014 for state housing assistance programs that stack with VA loan" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "VA home loan analysis with funding fee savings, PMI comparison, COE guidance, and stacking programs" }, "402": { "description": "Payment required" } } } }, "/api/vet/discounts": { "get": { "summary": "Verified veteran discounts by category", "description": "Returns verified veteran discounts organized by category. Airlines: United, Delta, American, Southwest military bereavement/active duty fares. Hotels: Marriott, Hilton, IHG, Wyndham veteran rates (often 10\u201320% off best available). Retail: Home Depot (10%), Lowe's (10%), Amazon Prime Military ($6.99/month), Apple Education pricing. Dining: major chain veteran specials especially on Veterans Day. National Parks: free lifetime America the Beautiful pass for veterans with service-connected disability (worth $80/year indefinitely). Financial: USAA, Navy Federal, PenFed veteran rates.", "operationId": "vetDiscounts", "x-price-usd": 0.05, "x-agent-use-case": "on-demand", "x-agent-chaining": "Chain at end of any veteran benefit discovery workflow \u2014 highest query volume, lowest cost; good for consumer-facing veteran agents as a value-add endpoint after disability or state benefits queries", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "travel", "retail", "dining", "recreation", "financial", "all" ] }, "description": "Discount category. Defaults to all." }, { "name": "disability_rating", "in": "query", "required": false, "schema": { "type": "string" }, "description": "VA disability rating \u2014 some discounts (national parks pass, additional state benefits) require service-connected disability" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language \u2014 any language supported" } ], "responses": { "200": { "description": "Verified veteran discounts by category with eligibility requirements and access instructions" }, "402": { "description": "Payment required" } } } } } }