{"openapi":"3.1.0","info":{"title":"Nepal Tax API","version":"1.0.0","description":"Nepal salary income-tax calculations over HTTP — the same engine that powers\n[salarytaxcalculatornepal.com](https://salarytaxcalculatornepal.com), so a payroll run and the\npublic calculator can never disagree.\n\n### Money on the wire\n\nAmounts you **send** are rupees, because that is what a payslip says. Amounts you **receive**\nare integer **paisa** (NPR × 100). Money is never a float in a response: NPR 1,234.56 comes\nback as `123456`. Divide by 100 once, at the point you show it to someone.\n\n### What it does not do\n\nNo accounts, no stored data, no ledger — every request is priced from the rate tables and\nforgotten. Nothing here is tax advice; confirm against the gazetted Finance Act before you\nfile anything.","contact":{"name":"NepalHRM","url":"https://salarytaxcalculatornepal.com"}},"tags":[{"name":"Calculate","description":"Price a salary, a target take-home, or two offers."},{"name":"Rates","description":"The statutory tables the engine reads."},{"name":"Meta","description":"Service health."}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"defaultFiscalYear":{"type":"string","enum":["2083/84","2082/83","2081/82"]},"fiscalYears":{"type":"array","items":{"type":"string","enum":["2083/84","2082/83","2081/82"]}},"uptimeSeconds":{"type":"number"}},"required":["status","version","defaultFiscalYear","fiscalYears","uptimeSeconds"]},"FiscalYearSummary":{"type":"object","properties":{"id":{"type":"string","enum":["2083/84","2082/83","2081/82"]},"adLabel":{"type":"string","example":"2026/27"},"startsOn":{"type":"string"},"coupleScheduleEnabled":{"type":"boolean"},"status":{"type":"string","enum":["enacted","proposed"]},"headline":{"type":"string"}},"required":["id","adLabel","startsOn","coupleScheduleEnabled","status","headline"]},"FiscalYearRules":{"type":"object","properties":{"id":{"type":"string","enum":["2083/84","2082/83","2081/82"]},"adLabel":{"type":"string","example":"2026/27"},"startsOn":{"type":"string"},"coupleScheduleEnabled":{"type":"boolean"},"bands":{"type":"object","properties":{"individual":{"type":"array","items":{"type":"object","properties":{"lower":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"upper":{"type":["integer","null"],"description":"Null on the open-ended top band.","example":123456},"rate":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"note":{"type":"string"},"sst":{"type":"boolean","description":"True on the 1% Social Security Tax band."}},"required":["lower","upper","rate"]}},"couple":{"type":"array","items":{"type":"object","properties":{"lower":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"upper":{"type":["integer","null"],"description":"Null on the open-ended top band.","example":123456},"rate":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"note":{"type":"string"},"sst":{"type":"boolean","description":"True on the 1% Social Security Tax band."}},"required":["lower","upper","rate"]}}},"required":["individual","couple"]},"caps":{"type":"object","properties":{"retirementCombined":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"citAmount":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"citPercentOfIncome":{"type":"number"},"lifeInsurance":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"medicalInsurance":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"ssfMonthlyBase":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["retirementCombined","citAmount","citPercentOfIncome","lifeInsurance","medicalInsurance","ssfMonthlyBase"]},"rates":{"type":"object","properties":{"pfEmployee":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"pfEmployer":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"ssfEmployee":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"ssfEmployer":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"femaleRebate":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01}},"required":["pfEmployee","pfEmployer","ssfEmployee","ssfEmployer","femaleRebate"]},"status":{"type":"string","enum":["enacted","proposed"]},"headline":{"type":"string"}},"required":["id","adLabel","startsOn","coupleScheduleEnabled","bands","caps","rates","status","headline"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]},"description":"Present on validation errors, one entry per bad field."}},"required":["code","message"]}},"required":["error"]},"CalculateResponse":{"type":"object","properties":{"input":{"$ref":"#/components/schemas/TaxInput"},"result":{"$ref":"#/components/schemas/TaxResult"},"levers":{"type":"array","items":{"$ref":"#/components/schemas/SavingLever"}}},"required":["input","result"]},"TaxInput":{"type":"object","properties":{"fiscalYear":{"type":"string","enum":["2083/84","2082/83","2081/82"],"default":"2083/84","description":"Nepali fiscal year the assessment runs under."},"maritalStatus":{"type":"string","enum":["single","married"],"default":"single","description":"Chooses the couple schedule where the fiscal year still has one. From FY 2083/84 both are taxed on the same table."},"gender":{"type":"string","enum":["male","female","other"],"default":"male","description":"A resident woman with employment income gets a 10% rebate on the computed tax."},"monthsWorked":{"type":"integer","minimum":1,"maximum":12,"default":12,"description":"Months of the fiscal year actually worked. Ignored when `periods` is sent — the periods then say how long the year was."},"startMonth":{"type":"integer","minimum":0,"maximum":11,"default":0,"description":"Which Nepali month the pay starts in: 0 = Shrawan … 11 = Ashad. Labels only — the tax on six months is the same whichever six they were. Pulled back if the year would not fit."},"periods":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SalaryPeriod"},"minItems":1,"maxItems":12,"default":null,"description":"The year as a sequence of pay rates, for a raise or a job change mid-year. Null — the normal case — means one flat rate taken from `monthlySalary` × `monthsWorked`."},"monthlySalary":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Monthly gross salary. Ignored when `periods` is sent.","example":80000},"monthlyAllowances":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Taxable monthly allowances on top of salary (transport, fuel, …).","example":0},"festivalBonus":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Dashain/festival bonus and any other one-off annual payment.","example":80000},"otherAnnualIncome":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Any other annual income assessed together with employment income.","example":0},"basicSalaryMonthly":{"type":["number","null"],"minimum":0,"maximum":100000000000,"default":null,"description":"Null means the whole monthly salary is the contribution base.","example":48000},"scheme":{"type":"string","enum":["none","pf","ssf"],"default":"none","description":"Approved retirement fund. SSF members do not pay the 1% Social Security Tax band; PF members do."},"citAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual Citizen Investment Trust contribution.","example":0},"lifeInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual life insurance premium.","example":0},"medicalInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual health insurance premium.","example":0}}},"SalaryPeriod":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64,"description":"Your own key for the period. Generated when omitted."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"How many months of the year this rate covers."},"monthlySalary":{"type":"number","minimum":0,"maximum":100000000000,"description":"Monthly gross salary while this rate was in force.","example":50000},"basicSalaryMonthly":{"type":["number","null"],"minimum":0,"maximum":100000000000,"default":null,"description":"Null means this period's own salary is the base.","example":30000}},"required":["months","monthlySalary"]},"TaxResult":{"type":"object","properties":{"fiscalYear":{"type":"string","enum":["2083/84","2082/83","2081/82"]},"rules":{"$ref":"#/components/schemas/FiscalYearRules"},"category":{"type":"string","enum":["individual","couple"],"description":"The schedule actually used."},"categoryDowngraded":{"type":"boolean","description":"True when a married person fell back to the single schedule."},"sstWaived":{"type":"boolean"},"monthsWorked":{"type":"integer"},"startMonth":{"type":"integer","description":"The Nepali month the pay started in. 0 = Shrawan."},"periods":{"type":"array","items":{"$ref":"#/components/schemas/PeriodResult"},"description":"The year broken into the rates it was actually paid at."},"salaryChanged":{"type":"boolean","description":"True when the salary was not the same all year."},"partYear":{"type":"boolean","description":"True when fewer than 12 months were paid."},"income":{"type":"object","properties":{"salary":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"allowances":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"festivalBonus":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"otherIncome":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"grossPay":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"employerRetirement":{"type":"integer","description":"The employer's contribution — itself a taxable benefit.","example":123456},"assessable":{"type":"integer","description":"grossPay + employerRetirement.","example":123456}},"required":["salary","allowances","festivalBonus","otherIncome","grossPay","employerRetirement","assessable"]},"contributions":{"type":"object","properties":{"employeeRetirement":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"employerRetirement":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"cit":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["employeeRetirement","employerRetirement","cit"]},"reliefs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["retirement","cit","life","medical"]},"label":{"type":"string"},"claimed":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"allowed":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"cappedBy":{"type":"string","description":"Set when allowed < claimed, naming the ceiling that bit."}},"required":["key","label","claimed","allowed"]}},"totalRelief":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"taxableIncome":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"bands":{"type":"array","items":{"type":"object","properties":{"lower":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"upper":{"type":["integer","null"],"description":"Amount in integer paisa (NPR × 100).","example":123456},"rate":{"type":"number","description":"The statutory rate for the band.","example":0.01},"appliedRate":{"type":"number","description":"The rate actually charged — 0 on the SST band for SSF members.","example":0.01},"waived":{"type":"boolean"},"note":{"type":"string"},"taxedAmount":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"tax":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["lower","upper","rate","appliedRate","waived","taxedAmount","tax"]}},"taxBeforeRebate":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"rebate":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"annualTax":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthlyTax":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"takeHome":{"type":"object","properties":{"annual":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthly":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["annual","monthly"]},"ownSavings":{"type":"object","properties":{"annual":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthly":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["annual","monthly"],"description":"Money that leaves the payslip but stays yours — PF/SSF and CIT balances."},"ctcAnnual":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"effectiveRate":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01},"marginalRate":{"type":"number","description":"A rate as a fraction: 0.01 is 1%.","example":0.01}},"required":["fiscalYear","rules","category","categoryDowngraded","sstWaived","monthsWorked","startMonth","periods","salaryChanged","partYear","income","contributions","reliefs","totalRelief","taxableIncome","bands","taxBeforeRebate","rebate","annualTax","monthlyTax","takeHome","ownSavings","ctcAnnual","effectiveRate","marginalRate"]},"PeriodResult":{"type":"object","properties":{"id":{"type":"string"},"months":{"type":"integer"},"firstMonth":{"type":"integer","description":"0 = Shrawan. Inclusive."},"lastMonth":{"type":"integer","description":"0 = Shrawan. Inclusive."},"monthlySalary":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthlyAllowances":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthlyGross":{"type":"integer","description":"Salary + allowances for one month.","example":123456},"gross":{"type":"integer","description":"Everything this period paid, over all its months.","example":123456},"employeeRetirement":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"employerRetirement":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"tax":{"type":"integer","description":"The share of the year's tax these months carry.","example":123456},"monthlyTax":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"cit":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"takeHome":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"monthlyTakeHome":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456}},"required":["id","months","firstMonth","lastMonth","monthlySalary","monthlyAllowances","monthlyGross","gross","employeeRetirement","employerRetirement","tax","monthlyTax","cit","takeHome","monthlyTakeHome"]},"SavingLever":{"type":"object","properties":{"key":{"type":"string","enum":["life","medical","cit","ssf"]},"label":{"type":"string"},"extraContribution":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"taxSaved":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"detail":{"type":"string"}},"required":["key","label","extraContribution","taxSaved","detail"]},"CalculateRequest":{"allOf":[{"$ref":"#/components/schemas/TaxInput"},{"type":"object","properties":{"includeLevers":{"type":"boolean","default":false,"description":"Also price the legal ways this person could still lower the bill (unused relief ceilings, SSF enrolment)."}}}]},"AcrossYearsResponse":{"type":"object","properties":{"input":{"$ref":"#/components/schemas/TaxInput"},"results":{"type":"array","items":{"$ref":"#/components/schemas/TaxResult"}}},"required":["input","results"]},"ReverseResponse":{"type":"object","properties":{"monthlySalary":{"type":"number","description":"The monthly gross, in rupees, that lands on the target."},"solved":{"type":"boolean","description":"False when even an implausibly large salary cannot reach the target."},"input":{"$ref":"#/components/schemas/TaxInput"},"result":{"$ref":"#/components/schemas/TaxResult"}},"required":["monthlySalary","solved","input","result"]},"ReverseRequest":{"type":"object","properties":{"targetMonthlyTakeHome":{"type":"number","minimum":0,"maximum":100000000000,"description":"The monthly cash-in-hand the person wants, in rupees.","example":100000},"basicPercent":{"type":"number","minimum":1,"maximum":100,"default":100,"description":"Basic salary as a percentage of gross. The PF/SSF base tracks the gross as the search moves."},"profile":{"type":"object","properties":{"fiscalYear":{"type":"string","enum":["2083/84","2082/83","2081/82"],"default":"2083/84","description":"Nepali fiscal year the assessment runs under."},"maritalStatus":{"type":"string","enum":["single","married"],"default":"single","description":"Chooses the couple schedule where the fiscal year still has one. From FY 2083/84 both are taxed on the same table."},"gender":{"type":"string","enum":["male","female","other"],"default":"male","description":"A resident woman with employment income gets a 10% rebate on the computed tax."},"monthsWorked":{"type":"integer","minimum":1,"maximum":12,"default":12,"description":"Months of the fiscal year actually worked. Ignored when `periods` is sent — the periods then say how long the year was."},"startMonth":{"type":"integer","minimum":0,"maximum":11,"default":0,"description":"Which Nepali month the pay starts in: 0 = Shrawan … 11 = Ashad. Labels only — the tax on six months is the same whichever six they were. Pulled back if the year would not fit."},"monthlyAllowances":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Taxable monthly allowances on top of salary (transport, fuel, …).","example":0},"festivalBonus":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Dashain/festival bonus and any other one-off annual payment.","example":80000},"otherAnnualIncome":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Any other annual income assessed together with employment income.","example":0},"scheme":{"type":"string","enum":["none","pf","ssf"],"default":"none","description":"Approved retirement fund. SSF members do not pay the 1% Social Security Tax band; PF members do."},"citAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual Citizen Investment Trust contribution.","example":0},"lifeInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual life insurance premium.","example":0},"medicalInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual health insurance premium.","example":0}},"default":{},"description":"Everything about the person except the salary being solved for."}},"required":["targetMonthlyTakeHome"]},"CompareResponse":{"type":"object","properties":{"offers":{"type":"array","prefixItems":[{"$ref":"#/components/schemas/Offer"},{"$ref":"#/components/schemas/Offer"}]},"results":{"type":"array","prefixItems":[{"$ref":"#/components/schemas/TaxResult"},{"$ref":"#/components/schemas/TaxResult"}]},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"note":{"type":"string"},"a":{"type":"number"},"b":{"type":"number"},"format":{"type":"string","enum":["money","percent"]},"better":{"type":["string","null"],"enum":["a","b",null]},"neutral":{"type":"boolean"},"emphasis":{"type":"boolean"}},"required":["key","label","a","b","format","better"]}},"verdict":{"type":"object","properties":{"cashWinner":{"type":["string","null"],"enum":["a","b",null]},"cashMonthly":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"cashAnnual":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"valueWinner":{"type":["string","null"],"enum":["a","b",null]},"valueAnnual":{"type":"integer","description":"Amount in integer paisa (NPR × 100).","example":123456},"flips":{"type":"boolean","description":"The interesting case: more cash on one side, more total value on the other."}},"required":["cashWinner","cashMonthly","cashAnnual","valueWinner","valueAnnual","flips"]}},"required":["offers","results","rows","verdict"]},"Offer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"default":"Offer"},"monthlySalary":{"type":"number","minimum":0,"maximum":100000000000,"description":"Monthly gross salary in this offer.","example":80000},"monthlyAllowances":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Monthly taxable allowances in this offer.","example":0},"festivalBonus":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Festival bonus in this offer.","example":80000},"scheme":{"type":"string","enum":["none","pf","ssf"],"default":"none"},"basicPercent":{"type":"number","minimum":1,"maximum":100,"default":60,"description":"Basic salary as a percentage of gross."}},"required":["monthlySalary"]},"CompareRequest":{"type":"object","properties":{"profile":{"type":"object","properties":{"fiscalYear":{"type":"string","enum":["2083/84","2082/83","2081/82"],"default":"2083/84","description":"Nepali fiscal year the assessment runs under."},"maritalStatus":{"type":"string","enum":["single","married"],"default":"single","description":"Chooses the couple schedule where the fiscal year still has one. From FY 2083/84 both are taxed on the same table."},"gender":{"type":"string","enum":["male","female","other"],"default":"male","description":"A resident woman with employment income gets a 10% rebate on the computed tax."},"monthsWorked":{"type":"integer","minimum":1,"maximum":12,"default":12,"description":"Months of the fiscal year actually worked. Ignored when `periods` is sent — the periods then say how long the year was."},"startMonth":{"type":"integer","minimum":0,"maximum":11,"default":0,"description":"Which Nepali month the pay starts in: 0 = Shrawan … 11 = Ashad. Labels only — the tax on six months is the same whichever six they were. Pulled back if the year would not fit."},"otherAnnualIncome":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Any other annual income assessed together with employment income.","example":0},"citAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual Citizen Investment Trust contribution.","example":0},"lifeInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual life insurance premium.","example":0},"medicalInsuranceAnnual":{"type":"number","minimum":0,"maximum":100000000000,"default":0,"description":"Annual health insurance premium.","example":0}},"default":{}},"offers":{"type":"array","prefixItems":[{"$ref":"#/components/schemas/Offer"},{"$ref":"#/components/schemas/Offer"}]}},"required":["offers"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Meta"],"summary":"Liveness probe","description":"Answers without touching anything else, so a load balancer can use it as a liveness check.","responses":{"200":{"description":"The service is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/fiscal-years":{"get":{"tags":["Rates"],"summary":"List the fiscal years this API can price","description":"Newest first. Use an `id` from here as the `fiscalYear` on any calculation.","responses":{"200":{"description":"Every fiscal year in the registry.","content":{"application/json":{"schema":{"type":"object","properties":{"fiscalYears":{"type":"array","items":{"$ref":"#/components/schemas/FiscalYearSummary"}}},"required":["fiscalYears"]}}}}}}},"/v1/fiscal-years/{id}":{"get":{"tags":["Rates"],"summary":"The full rate table for one fiscal year","description":"Slab edges, relief ceilings and contribution rates — everything the engine reads. Slab edges and ceilings are in paisa.","parameters":[{"schema":{"type":"string","description":"Fiscal year id. A slash inside a path segment has to be encoded, so `2083-84` is accepted as the URL-safe spelling of `2083%2F84`.","example":"2083-84"},"required":true,"description":"Fiscal year id. A slash inside a path segment has to be encoded, so `2083-84` is accepted as the URL-safe spelling of `2083%2F84`.","name":"id","in":"path"}],"responses":{"200":{"description":"The rules in force that year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalYearRules"}}}},"404":{"description":"No such fiscal year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/calculate":{"post":{"tags":["Calculate"],"summary":"Annual income tax on employment income","description":"Runs the Income Tax Act 2058 assessment in the order that people get wrong:\n\n1. Assessable income is pay **plus** the employer's retirement contribution — that contribution is itself a taxable benefit.\n2. Reliefs come off assessable income against their own ceilings, with PF/SSF and CIT sharing **one** NPR 5,00,000 ceiling; CIT only gets the room the mandatory contribution leaves behind.\n3. The slabs run on what is left.\n4. SSF members do not pay the 1% Social Security Tax band. PF members do.\n5. A resident woman's computed tax gets a 10% rebate, applied last.\n\nAmounts sent in are **rupees**. Every amount sent back is an integer in **paisa**.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"}}}},"responses":{"200":{"description":"The assessment, band by band.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"}}}},"400":{"description":"The body did not validate. `details` names each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/calculate/across-years":{"post":{"tags":["Calculate"],"summary":"The same person priced under every fiscal year","description":"Answers \"what would this salary have cost me last year?\". The `fiscalYear` in the body is ignored — every known year is returned, newest first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxInput"}}}},"responses":{"200":{"description":"One assessment per fiscal year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcrossYearsResponse"}}}},"400":{"description":"The body did not validate. `details` names each bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/reverse":{"post":{"tags":["Calculate"],"summary":"Gross salary for a wanted take-home","description":"\"I want NPR X in hand each month — what gross do I ask for?\"\n\nTake-home rises monotonically with gross, so this bisects rather than inverting the\nformula algebraically. That keeps working when a band edge, a relief ceiling or the SSF\nbase ceiling falls in the middle of the search. `solved: false` means even an\nimplausibly large salary could not reach the target — check the profile.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseRequest"}}}},"responses":{"200":{"description":"The gross that lands on the target, and the full assessment behind it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseResponse"}}}},"400":{"description":"The body did not validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/compare":{"post":{"tags":["Calculate"],"summary":"Two job offers, priced against each other","description":"Prices both offers for the same person and returns the rows a person actually weighs.\n\nThe row that decides it is **total value**: take-home plus the balances building in your\nname. An employer's SSF contribution never reaches your account, but it is still money you\nown — which is why the offer with the smaller gross often wins. `verdict.flips` is true\nwhen one offer pays more cash and the other is worth more overall.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}}},"responses":{"200":{"description":"Both assessments, the comparison rows, and the verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"400":{"description":"The body did not validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}