Planomy Tax Data Tax Data API

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.
  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:
    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.
    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
    EarningsTestLimit:
      type: object
      properties:
        monthly:
          type: number
        annual:
          type: number
        withholding:
          type: string
          description: Prose statement of the withholding ratio applied above the limit.
    PhaseOutRange:
      type: object
      description: Modified-AGI range over which a benefit phases down to zero.
      properties:
        start:
          type: number
        end:
          type: number
    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'
    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'
    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.
    BracketSet:
      type: object
      properties:
        single:
          type: array
          items:
            $ref: '#/components/schemas/Bracket'
        marriedJoint:
          type: array
          items:
            $ref: '#/components/schemas/Bracket'
    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
externalDocs:
  description: Planomy 2026 retirement and tax data (prose schema at
  url: https://planomy.net/data/