openapi: 3.2.0
info:
title: Planomy JSON Tax Data API
version: v1
summary: Free, keyless 2026 US retirement and tax figures as static JSON.
description: 'Planomy publishes the US federal tax, payroll, Social Security, Medicare/IRMAA, contribution-limit, phase-out and RMD figures that drive its local-first retirement planner as dated, source-attributed static JSON. There is no key, no sign-up and no quota: the dataset is two GET endpoints served as files from a Cloudflare CDN in front of planomy.net.
Every figure carries a `source` key that resolves into the document-level `sources` map, which in turn carries the publisher, the canonical IRS / SSA / CMS / Federal Register URL and the date Planomy last retrieved it. All money amounts are US dollars as bare numbers (no symbols, no separators) and all rates are decimal fractions, so `0.062` means 6.2%.
Planomy describes the contract as stable and additive: fields are added, never silently renamed or repurposed, and a breaking change would ship under a new `version` value.'
termsOfService: https://planomy.net/legal/terms
contact:
name: Planomy Support
email: support@planomy.net
url: https://planomy.net/data/
license:
name: US federal public-domain figures — free to reuse, attribution appreciated
url: https://planomy.net/data/
x-provenance:
authored-by: API Evangelist
method: generated
note: Planomy publishes no OpenAPI. This description was written by API Evangelist from live HTTP responses only. Every path, response field and example below was observed in a real 200 response on 2026-08-09 — see x-evidence on each operation. Nothing here is inferred beyond what the wire returned and what https://planomy.net/data/#schema documents in prose.
prose-schema: https://planomy.net/data/#schema
servers:
- url: https://planomy.net
description: Production (Cloudflare CDN in front of planomy.net)
tags:
- name: tax-data
description: Dated, source-attributed US tax and retirement figures.
paths:
/tax-data/index.json:
get:
operationId: getTaxDataIndex
summary: List available dataset years
description: Returns the manifest of published dataset years, the latest year, the URL template for resolving a year to its file, the prose schema URL and the licence statement. Call this first so a client can discover new years without hard-coding one.
tags:
- tax-data
security: []
responses:
'200':
description: The dataset manifest.
headers:
ETag:
description: Strong entity tag; send back as If-None-Match to revalidate.
schema:
type: string
Cache-Control:
description: 'Observed: public, max-age=0, must-revalidate'
schema:
type: string
Access-Control-Allow-Origin:
description: 'Observed: * — the endpoint is browser-fetchable cross-origin.'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/TaxDataIndex'
example:
latest: 2026
years:
- 2026
schema: https://planomy.net/data/#schema
documentation: https://planomy.net/data/
yearUrlTemplate: https://planomy.net/tax-data/{year}.json
license: Public-domain figures published by US federal agencies. Free to reuse; a link to https://planomy.net/data/ is appreciated.
'304':
description: Not modified — the ETag sent in If-None-Match still matches.
'404':
description: Not found. The origin serves an HTML 404 page, not a JSON error document; clients must branch on the status code and Content-Type rather than parsing a body.
content:
text/html:
schema:
type: string
x-evidence:
fetched: '2026-08-09'
url: https://planomy.net/tax-data/index.json
http_status: 200
content_type: application/json
/tax-data/{year}.json:
get:
operationId: getTaxDataYear
summary: Get the full tax and retirement dataset for a year
description: 'Returns the complete dated dataset for one tax year: federal brackets and standard deduction, FICA rates and wage base, Social Security COLA and earnings test, Medicare premiums, deductibles and IRMAA tiers, contribution limits (employer plans, IRA, SIMPLE, HSA, HDHP, health FSA), Roth/traditional-IRA and Saver''s Credit phase-outs, RMD applicable ages, and a set of state income-tax presets. Resolve `year` from getTaxDataIndex rather than hard-coding.'
tags:
- tax-data
security: []
parameters:
- name: year
in: path
required: true
description: A four-digit tax year listed in the `years` array of the index manifest.
schema:
type: integer
minimum: 2026
example: 2026
responses:
'200':
description: The dataset for the requested year.
headers:
ETag:
description: Strong entity tag; send back as If-None-Match to revalidate.
schema:
type: string
Cache-Control:
description: 'Observed: public, max-age=0, must-revalidate'
schema:
type: string
Access-Control-Allow-Origin:
description: 'Observed: * — the endpoint is browser-fetchable cross-origin.'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/TaxYearDataset'
examples:
year2026:
summary: Excerpt of the live 2026 dataset
externalValue: ../examples/planomy-tax-data-2026.json
'304':
description: Not modified — the ETag sent in If-None-Match still matches.
'404':
description: No dataset published for that year. The origin serves an HTML 404 page, not a JSON error document.
content:
text/html:
schema:
type: string
x-evidence:
fetched: '2026-08-09'
url: https://planomy.net/tax-data/2026.json
http_status: 200
content_type: application/json
components:
schemas:
BracketSet:
type: object
properties:
single:
type: array
items:
$ref: '#/components/schemas/Bracket'
marriedJoint:
type: array
items:
$ref: '#/components/schemas/Bracket'
PhaseOutRange:
type: object
description: Modified-AGI range over which a benefit phases down to zero.
properties:
start:
type: number
end:
type: number
SourceReference:
type: object
description: A citation for one upstream agency document.
required:
- title
- publisher
- url
properties:
title:
type: string
publisher:
type: string
description: 'Observed values: Internal Revenue Service, Social Security Administration, Centers for Medicare & Medicaid Services.'
url:
type: string
format: uri
retrieved:
type: string
format: date
description: Date Planomy last checked the figure against this document.
StateTaxPreset:
type: object
description: A state income-tax preset. `kind` is `flat` (with a single `rate`) or `brackets` (with a `brackets` set). The key `NONE` models a state with no income tax.
required:
- kind
properties:
kind:
type: string
enum:
- flat
- brackets
rate:
type: number
description: Present when kind is flat.
brackets:
$ref: '#/components/schemas/BracketSet'
IrmaaTier:
type: object
description: One income-related monthly adjustment tier, keyed off MAGI from two years prior.
properties:
magiMin:
type: number
partBMonthlySurcharge:
type: number
partBTotalMonthlyPremium:
type: number
partDMonthlySurcharge:
type: number
Bracket:
type: object
description: One marginal rate band; `min` is the lower bound of taxable income it applies from.
required:
- min
- rate
properties:
min:
type: number
description: Lower bound in US dollars.
rate:
type: number
description: Marginal rate as a decimal fraction.
TaxDataIndex:
type: object
description: Manifest of the published dataset years.
required:
- latest
- years
properties:
latest:
type: integer
description: The most recent published tax year.
years:
type: array
description: Every tax year with a published dataset file.
items:
type: integer
schema:
type: string
format: uri
description: URL of the prose field-level schema.
documentation:
type: string
format: uri
yearUrlTemplate:
type: string
description: RFC 6570-style template resolving a year to its dataset URL.
license:
type: string
TaxYearDataset:
type: object
description: The complete dataset for one tax year.
required:
- year
- version
- federal
- fica
- socialSecurity
- medicare
- contributionLimits
- phaseOuts
- rmd
properties:
year:
type: integer
version:
type: string
description: Contract version. A breaking change ships under a new value.
publishedAt:
type: string
format: date-time
lastUpdated:
type: string
format: date
schema:
type: string
format: uri
license:
type: string
sources:
type: object
description: Map of source key to citation; every `source` field elsewhere resolves here.
additionalProperties:
$ref: '#/components/schemas/SourceReference'
federal:
type: object
properties:
source:
type: string
brackets:
$ref: '#/components/schemas/BracketSet'
standardDeduction:
type: object
properties:
single:
type: number
marriedJoint:
type: number
marriedSeparate:
type: number
headOfHousehold:
type: number
fica:
type: object
properties:
source:
type: string
socialSecurityRate:
type: number
socialSecurityWageBase:
type: number
medicareRate:
type: number
additionalMedicareRate:
type: number
additionalMedicareThreshold:
type: object
properties:
single:
type: number
marriedJoint:
type: number
socialSecurity:
type: object
properties:
source:
type: string
colaRate:
type: number
wageBase:
type: number
quarterOfCoverage:
type: number
earningsTest:
type: object
properties:
underFullRetirementAge:
$ref: '#/components/schemas/EarningsTestLimit'
yearReachingFullRetirementAge:
$ref: '#/components/schemas/EarningsTestLimit'
medicare:
type: object
properties:
source:
type: string
notes:
type: string
partBMonthlyPremium:
type: number
partBAnnualDeductible:
type: number
partAInpatientDeductible:
type: number
partDMonthlyPremium:
type: number
irmaaTiers:
type: object
properties:
single:
type: array
items:
$ref: '#/components/schemas/IrmaaTier'
marriedJoint:
type: array
items:
$ref: '#/components/schemas/IrmaaTier'
contributionLimits:
type: object
properties:
employerPlans:
type: object
description: 401(k), 403(b), governmental 457(b) and the federal Thrift Savings Plan.
properties:
source:
type: string
note:
type: string
electiveDeferral:
type: number
catchUpAge50:
type: number
catchUpAge60To63:
type: number
totalAnnualAdditions:
type: number
annualCompensationLimit:
type: number
highlyCompensatedThreshold:
type: number
definedBenefitLimit:
type: number
ira:
type: object
properties:
source:
type: string
contribution:
type: number
catchUpAge50:
type: number
simple:
type: object
properties:
source:
type: string
deferral:
type: number
deferralHigherLimitPlans:
type: number
catchUpAge50:
type: number
catchUpAge60To63:
type: number
hsa:
type: object
properties:
source:
type: string
selfOnly:
type: number
family:
type: number
catchUpAge55:
type: number
catchUpSource:
type: string
catchUpNote:
type: string
hdhp:
type: object
properties:
source:
type: string
minimumDeductibleSelfOnly:
type: number
minimumDeductibleFamily:
type: number
maximumOutOfPocketSelfOnly:
type: number
maximumOutOfPocketFamily:
type: number
healthFsa:
type: object
properties:
source:
type: string
salaryReductionLimit:
type: number
maximumCarryover:
type: number
phaseOuts:
type: object
properties:
rothIra:
type: object
properties:
source:
type: string
note:
type: string
single:
$ref: '#/components/schemas/PhaseOutRange'
marriedJoint:
$ref: '#/components/schemas/PhaseOutRange'
marriedSeparate:
$ref: '#/components/schemas/PhaseOutRange'
traditionalIraDeduction:
type: object
properties:
source:
type: string
note:
type: string
singleCovered:
$ref: '#/components/schemas/PhaseOutRange'
marriedJointContributorCovered:
$ref: '#/components/schemas/PhaseOutRange'
marriedJointSpouseCoveredContributorNot:
$ref: '#/components/schemas/PhaseOutRange'
marriedSeparateCovered:
$ref: '#/components/schemas/PhaseOutRange'
saversCredit:
type: object
properties:
source:
type: string
note:
type: string
marriedJoint:
type: number
headOfHousehold:
type: number
singleOrMarriedSeparate:
type: number
rmd:
type: object
properties:
source:
type: string
note:
type: string
applicableAges:
type: array
items:
type: object
properties:
bornFrom:
type: integer
bornTo:
type:
- integer
- 'null'
age:
type: integer
requiredBeginningDate:
type: string
rothIraOwnerDistributionsRequired:
type: boolean
designatedRothAccountDistributionsRequired:
type: boolean
retirementContributionLimitDefaults:
type: object
description: Convenience defaults the Planomy planner seeds its inputs from.
properties:
employee401k:
type: number
states:
type: object
description: State income-tax presets keyed by USPS code, plus the pseudo-key `NONE`. Observed keys in the 2026 dataset - NONE, PA, IL, MA, VA, CA, NY, NJ, OR, MN.
additionalProperties:
$ref: '#/components/schemas/StateTaxPreset'
EarningsTestLimit:
type: object
properties:
monthly:
type: number
annual:
type: number
withholding:
type: string
description: Prose statement of the withholding ratio applied above the limit.
externalDocs:
description: Planomy 2026 retirement and tax data (prose schema at
url: https://planomy.net/data/