{"openapi":"3.1.0","info":{"title":"US Income Tax Calculator API","version":"1.0.0","license":{"name":"MIT","identifier":"MIT"},"description":"Free US federal, state and local income tax calculations, with no API key. The same calculation as https://income-tax.org. Amounts are US dollars per year unless labelled per_paycheck. FICA and state payroll programs are charged on gross wages; a 401(k)/IRA contribution and deductions lower income tax only. Tax data covers 2026, 2025, 2024, 2023. Estimates for a single wage earner, not tax advice. Also available as an MCP server at https://income-tax.org/mcp."},"servers":[{"url":"https://income-tax.org"}],"security":[],"externalDocs":{"description":"Parameters, examples and limits","url":"https://income-tax.org/developers/"},"paths":{"/api/calculate":{"get":{"operationId":"calculate","summary":"Calculate take-home pay","description":"Take-home pay and every federal, state and local tax for an annual gross income, with per-paycheck figures, taxable income, the marginal rate and a per-tax breakdown.","parameters":[{"name":"income","in":"query","required":true,"description":"Annual gross income in dollars.","schema":{"type":"number","minimum":0,"maximum":1000000000000}},{"name":"state","in":"query","required":true,"description":"US state, or district_of_columbia, in snake_case, e.g. new_york. States without an income tax (texas, florida, ...) are valid.","schema":{"type":"string","enum":["alabama","alaska","arizona","arkansas","california","colorado","connecticut","delaware","florida","georgia","hawaii","idaho","illinois","indiana","iowa","kansas","kentucky","louisiana","maine","maryland","massachusetts","michigan","minnesota","mississippi","missouri","montana","nebraska","nevada","new_hampshire","new_jersey","new_mexico","new_york","north_carolina","north_dakota","ohio","oklahoma","oregon","pennsylvania","rhode_island","south_carolina","south_dakota","tennessee","texas","utah","vermont","virginia","washington","west_virginia","wisconsin","wyoming","district_of_columbia"]}},{"name":"city","in":"query","required":false,"description":"Optional city or county with its own local taxes, in snake_case, e.g. new_york_city. Omit for state-level taxes only. An unknown city returns the list of valid ones for the state.","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Tax year. Defaults to the latest available, 2026.","schema":{"type":"string","enum":["2023","2024","2025","2026"]}},{"name":"filing_status","in":"query","required":false,"description":"Federal and state filing status.","schema":{"default":"single","type":"string","enum":["single","married","married_separately","head_of_household"]}},{"name":"retirement_contribution","in":"query","required":false,"description":"Annual pre-tax 401(k) / traditional IRA contribution in dollars. Reduces income tax but not FICA or other payroll taxes, and is subtracted from take-home. Capped at the year's 401(k) limit.","schema":{"default":0,"type":"number","minimum":0,"maximum":1000000000000}},{"name":"federal_deductions","in":"query","required":false,"description":"Total federal deductions in dollars (itemized, or any custom figure). Omit to use the standard deduction for the filing status.","schema":{"type":"number","minimum":0,"maximum":1000000000000}},{"name":"state_deductions","in":"query","required":false,"description":"Total state deductions in dollars. Omit to use the state's own standard deduction, including states that phase it out with income.","schema":{"type":"number","minimum":0,"maximum":1000000000000}},{"name":"exempt_taxes","in":"query","required":false,"description":"Taxes the filer is exempt from, e.g. [{ tax: 'social_security', scope: 'federal' }]. An unknown key returns the list of valid keys for the location. Sent as comma-separated scope:tax pairs, e.g. federal:social_security,city:city_income.","schema":{"type":"string"}},{"name":"pay_frequency","in":"query","required":false,"description":"Used to report per-paycheck amounts alongside annual ones.","schema":{"default":"monthly","type":"string","enum":["weekly","biweekly","semi_monthly","monthly"]}}],"responses":{"200":{"description":"Take-home pay, totals by jurisdiction, taxable income, credits, the marginal rate, a per-tax breakdown, notes, a link to the same result on the site, and `links.tax_tables`: the ready-made URL of the static tax-tables file for the brackets behind it.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The parameters are invalid, or name something the data does not have. `valid_values` lists what would be accepted, such as the cities a state has local tax data for.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"valid_values":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string"},"message":{"type":"string"}}}}},"required":["error"]}}}}}}},"/api/target":{"get":{"operationId":"target","summary":"Find gross income for a take-home goal","description":"Works backwards from a take-home goal, annual or per paycheck, to the lowest gross salary (to the cent) that reaches it, with the full breakdown at that salary.","parameters":[{"name":"take_home","in":"query","required":true,"description":"Desired take-home pay in dollars, after all taxes and the retirement contribution, per target_period.","schema":{"type":"number","exclusiveMinimum":0,"maximum":1000000000000}},{"name":"target_period","in":"query","required":false,"description":"Whether take_home is a yearly figure or a per-paycheck one (weekly, biweekly, semi_monthly, monthly).","schema":{"default":"annual","type":"string","enum":["annual","weekly","biweekly","semi_monthly","monthly"]}},{"name":"state","in":"query","required":true,"description":"US state, or district_of_columbia, in snake_case, e.g. new_york. States without an income tax (texas, florida, ...) are valid.","schema":{"type":"string","enum":["alabama","alaska","arizona","arkansas","california","colorado","connecticut","delaware","florida","georgia","hawaii","idaho","illinois","indiana","iowa","kansas","kentucky","louisiana","maine","maryland","massachusetts","michigan","minnesota","mississippi","missouri","montana","nebraska","nevada","new_hampshire","new_jersey","new_mexico","new_york","north_carolina","north_dakota","ohio","oklahoma","oregon","pennsylvania","rhode_island","south_carolina","south_dakota","tennessee","texas","utah","vermont","virginia","washington","west_virginia","wisconsin","wyoming","district_of_columbia"]}},{"name":"city","in":"query","required":false,"description":"Optional city or county with its own local taxes, in snake_case, e.g. new_york_city. Omit for state-level taxes only. An unknown city returns the list of valid ones for the state.","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Tax year. Defaults to the latest available, 2026.","schema":{"type":"string","enum":["2023","2024","2025","2026"]}},{"name":"filing_status","in":"query","required":false,"description":"Federal and state filing status.","schema":{"default":"single","type":"string","enum":["single","married","married_separately","head_of_household"]}},{"name":"retirement_contribution","in":"query","required":false,"description":"Annual pre-tax 401(k) / traditional IRA contribution in dollars. Reduces income tax but not FICA or other payroll taxes, and is subtracted from take-home. Capped at the year's 401(k) limit.","schema":{"default":0,"type":"number","minimum":0,"maximum":1000000000000}},{"name":"federal_deductions","in":"query","required":false,"description":"Total federal deductions in dollars (itemized, or any custom figure). Omit to use the standard deduction for the filing status.","schema":{"type":"number","minimum":0,"maximum":1000000000000}},{"name":"state_deductions","in":"query","required":false,"description":"Total state deductions in dollars. Omit to use the state's own standard deduction, including states that phase it out with income.","schema":{"type":"number","minimum":0,"maximum":1000000000000}},{"name":"exempt_taxes","in":"query","required":false,"description":"Taxes the filer is exempt from, e.g. [{ tax: 'social_security', scope: 'federal' }]. An unknown key returns the list of valid keys for the location. Sent as comma-separated scope:tax pairs, e.g. federal:social_security,city:city_income.","schema":{"type":"string"}},{"name":"pay_frequency","in":"query","required":false,"description":"Used to report per-paycheck amounts alongside annual ones.","schema":{"default":"monthly","type":"string","enum":["weekly","biweekly","semi_monthly","monthly"]}}],"responses":{"200":{"description":"required_gross_income, the target restated as annual, and the full calculate result at that income.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The parameters are invalid, or name something the data does not have. `valid_values` lists what would be accepted, such as the cities a state has local tax data for.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"valid_values":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string"},"message":{"type":"string"}}}}},"required":["error"]}}}}}}},"/api/tax-tables":{"get":{"operationId":"taxTables","summary":"Look up tax brackets and rates","description":"The brackets, rates, standard deductions, credits and 401(k) limit the calculator uses, plus the state's sales tax rates, for a year, state and optional city. Each schedule is labelled with how it is applied (`kind`) and the income it is charged on (`basis`); `how_to_read` explains both. Use calculate for dollar amounts. Unfiltered tables (every filing status) are also published as free static files at /data/tax-tables/{year}/{state}/{city}.json, dash-case, e.g. /data/tax-tables/2026/oregon/portland.json; drop /{city} for a state, or both for federal only.","parameters":[{"name":"year","in":"query","required":false,"description":"Tax year. Defaults to the latest available, 2026.","schema":{"type":"string","enum":["2023","2024","2025","2026"]}},{"name":"state","in":"query","required":false,"description":"US state in snake_case, e.g. new_york. Omit for federal tables only.","schema":{"type":"string","enum":["alabama","alaska","arizona","arkansas","california","colorado","connecticut","delaware","florida","georgia","hawaii","idaho","illinois","indiana","iowa","kansas","kentucky","louisiana","maine","maryland","massachusetts","michigan","minnesota","mississippi","missouri","montana","nebraska","nevada","new_hampshire","new_jersey","new_mexico","new_york","north_carolina","north_dakota","ohio","oklahoma","oregon","pennsylvania","rhode_island","south_carolina","south_dakota","tennessee","texas","utah","vermont","virginia","washington","west_virginia","wisconsin","wyoming","district_of_columbia"]}},{"name":"city","in":"query","required":false,"description":"Optional city or county, e.g. new_york_city, to include its local tables, or a city with its own sales tax rate, e.g. seattle. Without one, the response lists the state's cities so you can ask again.","schema":{"type":"string"}},{"name":"filing_status","in":"query","required":false,"description":"Return only the schedules for this filing status. Omit for all four.","schema":{"type":"string","enum":["single","married","married_separately","head_of_household"]}},{"name":"tax_types","in":"query","required":false,"description":"Return only these tax types, e.g. ['federal_income', 'state_income'], or ['sales_tax'] for the state's sales tax rates alone. Omit for all. Unknown keys return the valid ones. Comma-separated.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Schedules by jurisdiction, sales tax rates by period, how_to_read notes and a link to the site's tax tables.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The parameters are invalid, or name something the data does not have. `valid_values` lists what would be accepted, such as the cities a state has local tax data for.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"valid_values":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string"},"message":{"type":"string"}}}}},"required":["error"]}}}}}}}}}