{"openapi":"3.1.0","info":{"title":"Salary After Tax API","version":"1.0.0","description":"Serverless API that calculates U.S. payroll taxes, state taxes, deductions, and take-home pay per pay period.","contact":{"name":"Support","email":"support@example.com"}},"servers":[{"url":"https://{host}","description":"Deployment server","variables":{"host":{"default":"localhost:3000","description":"Replace with your Vercel or RapidAPI domain."}}}],"tags":[{"name":"Health","description":"Health check endpoints"},{"name":"Taxes","description":"Payroll tax calculation endpoints"}],"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Health check","operationId":"getHealthStatus","responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/calculate":{"get":{"tags":["Taxes"],"summary":"Endpoint metadata","operationId":"getCalculateMeta","responses":{"200":{"description":"Metadata describing the tax calculation endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateMeta"}}}}}},"post":{"tags":["Taxes"],"summary":"Calculate payroll taxes and net income","operationId":"postCalculateTaxes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxCalculationRequest"}}}},"responses":{"200":{"description":"Calculation successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxCalculationSuccessResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxCalculationValidationErrorResponse"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/state-specific-taxes":{"get":{"tags":["Taxes"],"summary":"List available state-specific tax types","operationId":"getStateSpecificTaxMetadata","responses":{"200":{"description":"State-specific tax metadata","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StateSpecificTaxMetadata"}}}}}}}}},"components":{"schemas":{"PayFrequency":{"type":"string","enum":["Weekly","Bi-weekly","Semi-monthly","Monthly","Annually"]},"FilingStatus":{"type":"string","enum":["Single","Married Filing Jointly","Married Filing Separately","Head of Household"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"message":{"type":"string","example":"Salary After Tax API is healthy."},"timestamp":{"type":"string","format":"date-time"}},"required":["status","message","timestamp"]},"CalculateMeta":{"type":"object","properties":{"name":{"type":"string","example":"US Payroll Tax Calculator"},"version":{"type":"string","example":"1.0.0"},"description":{"type":"string","example":"Calculate US payroll taxes, deductions, and net pay per pay period."},"methods":{"type":"array","items":{"type":"string","enum":["POST"]},"example":["POST"]},"docs":{"type":"string","example":"/api/docs"},"note":{"type":"string","example":"Send a POST request with the required income, filing status, and deduction details."}},"required":["name","version","description","methods","docs","note"]},"MoneyAmount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"example":300},"frequency":{"type":"string","enum":["Weekly","Bi-weekly","Semi-monthly","Monthly","Annually"]}},"required":["amount","frequency"],"additionalProperties":false},"IncomeBase":{"allOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"object","properties":{"amount":{"type":"number","minimum":0.01}}}]},"Income":{"type":"object","properties":{"base":{"$ref":"#/components/schemas/IncomeBase"},"additional":{"type":"array","items":{"$ref":"#/components/schemas/MoneyAmount"},"description":"Optional list of supplemental income (bonuses, commissions, etc)."}},"required":["base"],"additionalProperties":false},"Dependents":{"type":"object","properties":{"children":{"type":"integer","minimum":0,"maximum":20,"description":"Children under 17.","example":1},"adults":{"type":"integer","minimum":0,"maximum":20,"description":"Other qualifying dependents.","example":0}},"additionalProperties":false},"RetirementPlan":{"type":"object","properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"Retirement contribution as a percent of gross pay.","example":5},"fixedAnnual":{"type":"number","minimum":0,"description":"Fixed annual retirement contribution (in dollars).","example":2000}},"additionalProperties":false},"PreTaxDeduction":{"type":"object","properties":{"amount":{"type":"number","minimum":0},"frequency":{"type":"string","enum":["Weekly","Bi-weekly","Semi-monthly","Monthly","Annually"]},"type":{"type":"string","enum":["healthInsurance","healthcareFsa","dependentCareFsa","hsa","other"]}},"required":["amount","frequency","type"],"additionalProperties":false},"Deduction":{"$ref":"#/components/schemas/MoneyAmount"},"Deductions":{"type":"object","properties":{"preTax":{"type":"array","items":{"$ref":"#/components/schemas/PreTaxDeduction"}},"retirement":{"$ref":"#/components/schemas/RetirementPlan"},"itemized":{"type":"array","items":{"$ref":"#/components/schemas/Deduction"}}},"additionalProperties":false},"StateSpecificTaxes":{"type":"object","properties":{"SDI":{"type":"number","nullable":true},"TDI":{"type":"number","nullable":true},"DBL":{"type":"number","nullable":true},"PFML":{"type":"number","nullable":true},"PFL":{"type":"number","nullable":true},"FLI":{"type":"number","nullable":true},"SUI":{"type":"number","nullable":true},"MunicipalTax":{"type":"number","nullable":true},"EIT":{"type":"number","nullable":true},"LST":{"type":"number","nullable":true},"SchoolDistrictTax":{"type":"number","nullable":true},"MentalHealthTax":{"type":"number","nullable":true},"WBF":{"type":"number","nullable":true}},"additionalProperties":false},"StateSpecificTaxMetadata":{"type":"object","properties":{"id":{"type":"string","enum":["SDI","TDI","DBL","PFML","PFL","FLI","SUI","MunicipalTax","EIT","LST","SchoolDistrictTax","MentalHealthTax","WBF"]},"description":{"type":"string"},"states":{"type":"array","items":{"type":"string","enum":["AK","AL","AR","AZ","CA","CO","CT","DC","DE","FL","GA","HI","IA","ID","IL","IN","KS","KY","LA","MA","MD","ME","MI","MN","MO","MS","MT","NC","ND","NE","NH","NJ","NM","NV","NY","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VA","VT","WA","WI","WV","WY"]}}},"required":["id","description","states"],"additionalProperties":false},"TaxesBeforeExemptions":{"type":"object","properties":{"stateSpecificTaxes":{"$ref":"#/components/schemas/StateSpecificTaxes"},"federalIncomeTax":{"type":"number"},"socialSecurityTax":{"type":"number"},"medicareTax":{"type":"number"}},"required":["stateSpecificTaxes","federalIncomeTax","socialSecurityTax","medicareTax"]},"RetirementBenefitDetail":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"}},"required":["label","amount"]},"TaxCalculationDetailBreakdown":{"type":"object","properties":{"grossIncome":{"type":"number"},"grossIncomeAnnual":{"type":"number"},"adjustedGrossIncome":{"type":"number"},"taxableIncome":{"type":"number"},"standardDeduction":{"type":"number"},"itemizedDeduction":{"type":"number","nullable":true},"preTax":{"type":"object","properties":{"fica":{"type":"number"},"agi":{"type":"number"}},"required":["fica","agi"]},"retirements":{"type":"object","properties":{"total":{"type":"number"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/RetirementBenefitDetail"}}},"required":["total","breakdown"]},"overtimeIncome":{"type":"number"},"hourlyIncome":{"type":"number"}},"required":["grossIncome","grossIncomeAnnual","adjustedGrossIncome","taxableIncome","standardDeduction","preTax","retirements","overtimeIncome","hourlyIncome"]},"TaxCalculationSummary":{"type":"object","properties":{"perPeriod":{"type":"object","properties":{"gross":{"type":"number"},"taxes":{"type":"number"},"takeHome":{"type":"number"}},"required":["gross","taxes","takeHome"]},"annual":{"type":"object","properties":{"gross":{"type":"number"},"taxes":{"type":"number"},"takeHome":{"type":"number"}},"required":["gross","taxes","takeHome"]}},"required":["perPeriod","annual"]},"TaxCredits":{"type":"object","properties":{"dependents":{"type":"number"},"earnedIncome":{"type":"number"}},"required":["dependents","earnedIncome"]},"TaxCalculationTaxes":{"type":"object","properties":{"federal":{"type":"object","properties":{"incomeTax":{"type":"number"},"socialSecurity":{"type":"number"},"medicare":{"type":"number"},"credits":{"$ref":"#/components/schemas/TaxCredits"}},"required":["incomeTax","socialSecurity","medicare","credits"]},"state":{"type":"object","properties":{"incomeTax":{"type":"number"},"special":{"$ref":"#/components/schemas/StateSpecificTaxes"}},"required":["incomeTax","special"]},"totalFederal":{"type":"number"},"totalState":{"type":"number"},"total":{"type":"number"}},"required":["federal","state","totalFederal","totalState","total"]},"FederalTaxExemptions":{"type":"object","properties":{"socialSecurity":{"type":"boolean"},"medicare":{"type":"boolean"},"federalIncomeTax":{"type":"boolean"}},"additionalProperties":false},"StateTaxExemptions":{"type":"object","properties":{"SDI":{"type":"boolean"},"TDI":{"type":"boolean"},"DBL":{"type":"boolean"},"PFML":{"type":"boolean"},"PFL":{"type":"boolean"},"FLI":{"type":"boolean"},"SUI":{"type":"boolean"},"MunicipalTax":{"type":"boolean"},"EIT":{"type":"boolean"},"LST":{"type":"boolean"},"SchoolDistrictTax":{"type":"boolean"},"MentalHealthTax":{"type":"boolean"},"WBF":{"type":"boolean"}},"additionalProperties":false},"ExemptionsInput":{"type":"object","properties":{"federal":{"$ref":"#/components/schemas/FederalTaxExemptions"},"state":{"$ref":"#/components/schemas/StateTaxExemptions"}},"additionalProperties":false},"TaxCalculationRequest":{"type":"object","properties":{"income":{"$ref":"#/components/schemas/Income"},"payFrequency":{"$ref":"#/components/schemas/PayFrequency"},"location":{"type":"object","properties":{"state":{"type":"string","enum":["AK","AL","AR","AZ","CA","CO","CT","DC","DE","FL","GA","HI","IA","ID","IL","IN","KS","KY","LA","MA","MD","ME","MI","MN","MO","MS","MT","NC","ND","NE","NH","NJ","NM","NV","NY","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VA","VT","WA","WI","WV","WY"],"description":"Optional two-letter state or District of Columbia code."}},"additionalProperties":false},"filing":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/FilingStatus"},"dependents":{"$ref":"#/components/schemas/Dependents"}},"required":["status"]},"deductions":{"$ref":"#/components/schemas/Deductions"},"exemptions":{"$ref":"#/components/schemas/ExemptionsInput"},"extraWithholding":{"type":"number","minimum":0,"description":"Extra withholding per pay period.","example":50}},"required":["income","payFrequency","filing"],"additionalProperties":false},"TaxCalculationSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true},"summary":{"$ref":"#/components/schemas/TaxCalculationSummary"},"taxes":{"$ref":"#/components/schemas/TaxCalculationTaxes"},"details":{"$ref":"#/components/schemas/TaxCalculationDetailBreakdown"}},"required":["success","summary","taxes","details"]},"TaxCalculationValidationErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","example":"Validation failed"},"details":{"type":"object","description":"Zod formatted validation errors","additionalProperties":true}},"required":["success","error","details"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","example":"Failed to calculate taxes"},"details":{"type":"object","description":"Additional error information","additionalProperties":true}},"required":["success","error"]}}}}