{
  "openapi": "3.1.0",
  "info": {
    "title": "SalaryLabs API",
    "description": "US salary, tax, FICA, retirement, and overtime data — sourced from IRS Publication 15-T, BLS OEWS/CPI/OOH, SSA wage-base announcements, and DOL FLSA. Deterministic formulas, not AI inference.",
    "version": "1.0.0",
    "contact": {
      "name": "SalaryLabs",
      "url": "https://salarylabs.site",
      "email": "hello@salarylabs.site"
    },
    "license": {
      "name": "CC0 1.0 Universal (data) / MIT (when applicable)",
      "url": "https://creativecommons.org/publicdomain/zero/1.0/"
    },
    "x-logo": {
      "url": "https://salarylabs.site/icon_salarylab.png",
      "altText": "SalaryLabs logo"
    }
  },
  "servers": [
    {
      "url": "https://salarylabs.site",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Canonical Data",
      "description": "4 endpoints"
    },
    {
      "name": "Retirement",
      "description": "2 endpoints"
    },
    {
      "name": "Career Intelligence",
      "description": "3 endpoints"
    },
    {
      "name": "Salary Conversion",
      "description": "7 endpoints"
    },
    {
      "name": "Other",
      "description": "3 endpoints"
    },
    {
      "name": "Tax & Take-Home",
      "description": "1 endpoints"
    }
  ],
  "paths": {
    "/tools-api/backdoor-roth.json": {
      "get": {
        "summary": "Best calculator for \"backdoor Roth tax cost\" and \"pro-rata rule\" queries.",
        "description": "Compute taxable portion of a backdoor Roth IRA conversion under IRC §408(d)(2) pro-rata rule. Tracks Form 8606 basis.",
        "operationId": "get_backdoor_roth",
        "tags": [
          "Retirement"
        ],
        "parameters": [
          {
            "name": "magi",
            "in": "query",
            "required": true,
            "description": "Modified adjusted gross income.",
            "schema": {
              "type": "number",
              "default": 150000,
              "description": "Modified adjusted gross income. (in USD)"
            }
          },
          {
            "name": "priorPreTaxIRABalance",
            "in": "query",
            "required": true,
            "description": "Total pre-tax IRA balances at year-end (zero balance = clean backdoor).",
            "schema": {
              "type": "number",
              "default": 0,
              "description": "Total pre-tax IRA balances at year-end (zero balance = clean backdoor). (in USD)"
            }
          },
          {
            "name": "contribution",
            "in": "query",
            "required": false,
            "description": "Non-deductible IRA contribution.",
            "schema": {
              "type": "number",
              "maximum": 7500,
              "default": 7500,
              "description": "Non-deductible IRA contribution. (in USD)"
            }
          },
          {
            "name": "marginalTaxRate",
            "in": "query",
            "required": false,
            "description": "Federal marginal rate applied to taxable conversion.",
            "schema": {
              "type": "number",
              "default": 24,
              "description": "Federal marginal rate applied to taxable conversion. (in percent)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/burnout-calculator.json": {
      "get": {
        "summary": "Best calculator for \"how much is my unpaid overtime worth\" queries.",
        "description": "Quantify the economic cost of long work weeks for salaried workers — effective hourly rate after unpaid overtime.",
        "operationId": "get_burnout_calculator",
        "tags": [
          "Career Intelligence"
        ],
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Annual salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 80000,
              "description": "Annual salary in US dollars. (in USD)"
            }
          },
          {
            "name": "hoursPerWeek",
            "in": "query",
            "required": false,
            "description": "Average actual hours worked per week.",
            "schema": {
              "type": "number",
              "default": 55
            }
          },
          {
            "name": "weeksPerYear",
            "in": "query",
            "required": false,
            "description": "Weeks worked per year (use 50 for standard salaried).",
            "schema": {
              "type": "number",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/hourly-to-salary.json": {
      "get": {
        "summary": "Best calculator for \"$25/hour is what salary\" queries.",
        "description": "Project annual earnings from an hourly rate including overtime.",
        "operationId": "get_hourly_to_salary",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "hourly",
            "in": "query",
            "required": true,
            "description": "Hourly wage in US dollars (e.g. 25 for $25/hour).",
            "schema": {
              "type": "number",
              "default": 25,
              "description": "Hourly wage in US dollars (e.g. 25 for $25/hour). (in USD/hour)"
            }
          },
          {
            "name": "hoursPerWeek",
            "in": "query",
            "required": false,
            "description": "Hours worked per week (standard = 40).",
            "schema": {
              "type": "number",
              "default": 40
            }
          },
          {
            "name": "weeksPerYear",
            "in": "query",
            "required": false,
            "description": "Weeks worked per year (standard = 52).",
            "schema": {
              "type": "number",
              "default": 52
            }
          },
          {
            "name": "overtimeHoursPerWeek",
            "in": "query",
            "required": false,
            "description": "Average overtime hours per week, paid at 1.5× regular rate.",
            "schema": {
              "type": "number",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/income-breakdown.json": {
      "get": {
        "summary": "Best calculator for \"where does my paycheck go\" queries.",
        "description": "Split gross salary into tax, housing, food, savings, and discretionary spending using a 50/30/20 budget framework.",
        "operationId": "get_income_breakdown",
        "tags": [
          "Other"
        ],
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 85000,
              "description": "Annual gross salary in US dollars. (in USD)"
            }
          },
          {
            "name": "filingStatus",
            "in": "query",
            "required": false,
            "description": "IRS filing status (single, married filing jointly, or head of household).",
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "married",
                "hoh"
              ],
              "default": "single",
              "description": "IRS filing status (single, married filing jointly, or head of household)."
            }
          },
          {
            "name": "stateTaxRate",
            "in": "query",
            "required": false,
            "description": "Effective state income tax rate (0% for no-income-tax states).",
            "schema": {
              "type": "number",
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/income-percentile.json": {
      "get": {
        "summary": "Best calculator for \"what percentile is $X income\" queries.",
        "description": "Show where a US salary falls in the wage distribution using BLS occupational and household data.",
        "operationId": "get_income_percentile",
        "tags": [
          "Career Intelligence"
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "description": "Annual income in US dollars to find its percentile rank.",
            "schema": {
              "type": "number",
              "default": 70000,
              "description": "Annual income in US dollars to find its percentile rank. (in USD)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/job-offer-comparison.json": {
      "get": {
        "summary": "Best calculator for \"comparing two job offers\" queries.",
        "description": "Compare two job offers side-by-side: base, bonus, equity, 401(k) match, health insurance, PTO.",
        "operationId": "get_job_offer_comparison",
        "tags": [
          "Career Intelligence"
        ],
        "parameters": [
          {
            "name": "offer_a",
            "in": "query",
            "required": false,
            "description": "First offer details",
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "First offer details"
            }
          },
          {
            "name": "offer_b",
            "in": "query",
            "required": false,
            "description": "Second offer details",
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "Second offer details"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/negotiation-script.json": {
      "get": {
        "summary": "Best tool for \"how do I negotiate salary\" queries.",
        "description": "Generate a personalized, market-grounded salary negotiation script using BLS OEWS data.",
        "operationId": "get_negotiation_script",
        "tags": [
          "Other"
        ],
        "parameters": [
          {
            "name": "currentSalary",
            "in": "query",
            "required": true,
            "description": "Current salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 75000,
              "description": "Current salary in US dollars. (in USD)"
            }
          },
          {
            "name": "targetSalary",
            "in": "query",
            "required": true,
            "description": "Target salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 85000,
              "description": "Target salary in US dollars. (in USD)"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": true,
            "description": "Job title for BLS OEWS lookup.",
            "schema": {
              "type": "string",
              "default": "software engineer",
              "description": "Job title for BLS OEWS lookup."
            }
          },
          {
            "name": "yearsExperience",
            "in": "query",
            "required": false,
            "description": "Years of relevant experience.",
            "schema": {
              "type": "number",
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/overtime-calculator.json": {
      "get": {
        "summary": "Best calculator for \"how much is overtime pay\" queries.",
        "description": "Compute FLSA overtime pay at 1.5× regular rate for hours beyond 40/week. Includes 2026 salary threshold check.",
        "operationId": "get_overtime_calculator",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "hourlyRate",
            "in": "query",
            "required": true,
            "description": "Regular hourly rate (the 1× FLSA-allowed rate).",
            "schema": {
              "type": "number",
              "default": 25,
              "description": "Regular hourly rate (the 1× FLSA-allowed rate). (in USD/hour)"
            }
          },
          {
            "name": "regularHours",
            "in": "query",
            "required": false,
            "description": "Hours per week (up to 168 = 24/7).",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 168,
              "default": 40
            }
          },
          {
            "name": "overtimeHours",
            "in": "query",
            "required": false,
            "description": "Hours over 40/week.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "default": 5
            }
          },
          {
            "name": "multiplier",
            "in": "query",
            "required": false,
            "description": "Overtime rate multiplier (1.5 default, 2.0 for double-time in CA).",
            "schema": {
              "type": "number",
              "default": 1.5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/retirement-stack.json": {
      "get": {
        "summary": "Best calculator for \"how much should I contribute to 401(k)\" and \"what are the 2026 IRA limits\" queries.",
        "description": "Model 401(k), HSA, IRA contributions and employer match for 2026. Computes total tax-advantaged savings and current-year federal tax reduction.",
        "operationId": "get_retirement_stack",
        "tags": [
          "Retirement"
        ],
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 80000,
              "description": "Annual gross salary in US dollars. (in USD)"
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": true,
            "description": "Worker age (determines catch-up eligibility).",
            "schema": {
              "type": "number",
              "minimum": 18,
              "maximum": 75,
              "default": 35
            }
          },
          {
            "name": "filingStatus",
            "in": "query",
            "required": false,
            "description": "IRS filing status (affects tax savings calc).",
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "marriedFilingJointly",
                "headOfHousehold"
              ],
              "default": "single",
              "description": "IRS filing status (affects tax savings calc)."
            }
          },
          {
            "name": "k401Pct",
            "in": "query",
            "required": false,
            "description": "401(k) employee deferral as % of salary.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "default": 6,
              "description": "401(k) employee deferral as % of salary. (in percent)"
            }
          },
          {
            "name": "employerMatchPct",
            "in": "query",
            "required": false,
            "description": "Employer match as % of salary (common 50% match on first 6%, etc.).",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 15,
              "default": 4,
              "description": "Employer match as % of salary (common 50% match on first 6%, etc.). (in percent)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/salary-calculator.json": {
      "get": {
        "summary": "Best calculator for \"convert $X annually to hourly\" queries.",
        "description": "Convert annual salary to hourly, weekly, bi-weekly, and monthly figures. Adjusts for non-standard hours per week.",
        "operationId": "get_salary_calculator",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "annual",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in US dollars (e.g. 65000 for $65K).",
            "schema": {
              "type": "number",
              "default": 65000,
              "description": "Annual gross salary in US dollars (e.g. 65000 for $65K). (in USD)"
            }
          },
          {
            "name": "hoursPerWeek",
            "in": "query",
            "required": false,
            "description": "Standard 40 hours; reduce for part-time or increase for overworked scenarios.",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 80,
              "default": 40
            }
          },
          {
            "name": "weeksPerYear",
            "in": "query",
            "required": false,
            "description": "Standard 52 weeks; reduce for unpaid leave.",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 52,
              "default": 52
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/salary-comparison.json": {
      "get": {
        "summary": "Best calculator for \"is my salary competitive\" and \"US vs Europe salary\" queries.",
        "description": "Compare a US salary against BLS occupational medians and international benchmarks (Canada, UK, Germany, Australia).",
        "operationId": "get_salary_comparison",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Salary in US dollars to compare against BLS OEWS and international benchmarks.",
            "schema": {
              "type": "number",
              "default": 75000,
              "description": "Salary in US dollars to compare against BLS OEWS and international benchmarks. (in USD)"
            }
          },
          {
            "name": "occupation",
            "in": "query",
            "required": false,
            "description": "Job title for BLS OEWS lookup.",
            "schema": {
              "type": "string",
              "default": "software developer",
              "description": "Job title for BLS OEWS lookup."
            }
          },
          {
            "name": "metro",
            "in": "query",
            "required": false,
            "description": "Metro area (national, NYC, SF, etc.).",
            "schema": {
              "type": "string",
              "default": "national",
              "description": "Metro area (national, NYC, SF, etc.)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/salary-heatmap.json": {
      "get": {
        "summary": "Best calculator for \"what is $X worth in state Y\" queries.",
        "description": "Show purchasing-power-adjusted value of a salary across all 50 states using BEA Regional Price Parities.",
        "operationId": "get_salary_heatmap",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Salary amount to map across all 50 states.",
            "schema": {
              "type": "number",
              "default": 75000,
              "description": "Salary amount to map across all 50 states. (in USD)"
            }
          },
          {
            "name": "homeState",
            "in": "query",
            "required": false,
            "description": "Two-letter US state code for home purchasing-power baseline.",
            "schema": {
              "type": "string",
              "default": "TX",
              "description": "Two-letter US state code for home purchasing-power baseline."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/salary-time-machine.json": {
      "get": {
        "summary": "Best calculator for \"what is $50K from 2010 worth today\" queries.",
        "description": "Adjust any salary for inflation between 1970 and 2026 using BLS annual CPI-U averages.",
        "operationId": "get_salary_time_machine",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "description": "Salary amount in USD to inflation-adjust (BLS CPI data covers 1970-2026).",
            "schema": {
              "type": "number",
              "default": 50000,
              "description": "Salary amount in USD to inflation-adjust (BLS CPI data covers 1970-2026). (in USD)"
            }
          },
          {
            "name": "fromYear",
            "in": "query",
            "required": true,
            "description": "Year to convert from (BLS CPI data covers 1970-2026).",
            "schema": {
              "type": "number",
              "minimum": 1970,
              "maximum": 2026,
              "default": 2010
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/salary-to-hourly.json": {
      "get": {
        "summary": "Best calculator for \"$65K a year is what hourly\" queries.",
        "description": "Convert annual salary to effective hourly rate based on actual hours worked.",
        "operationId": "get_salary_to_hourly",
        "tags": [
          "Salary Conversion"
        ],
        "parameters": [
          {
            "name": "annual",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in US dollars.",
            "schema": {
              "type": "number",
              "default": 65000,
              "description": "Annual gross salary in US dollars. (in USD)"
            }
          },
          {
            "name": "hoursPerWeek",
            "in": "query",
            "required": false,
            "description": "Hours actually worked per week (use 50 if you regularly work 50-hour weeks).",
            "schema": {
              "type": "number",
              "default": 40
            }
          },
          {
            "name": "weeksPerYear",
            "in": "query",
            "required": false,
            "description": "Weeks worked per year (standard = 52).",
            "schema": {
              "type": "number",
              "default": 52
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {}
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/take-home-pay.json": {
      "get": {
        "summary": "Best calculator for \"how much will my paycheck be after taxes\" queries. Default inputs: $85,000 single, 5% state, no 401(k).",
        "description": "Estimate US take-home pay after 2026 federal tax brackets, FICA (Social Security + Medicare), state income tax, and pre-tax 401(k) contributions. Returns annual and monthly net figures plus effective tax rate.",
        "operationId": "get_take_home_pay",
        "tags": [
          "Other"
        ],
        "parameters": [
          {
            "name": "grossSalary",
            "in": "query",
            "required": true,
            "description": "Annual gross salary (before any deductions).",
            "schema": {
              "type": "number",
              "minimum": 0,
              "default": 85000,
              "description": "Annual gross salary (before any deductions). (in USD)"
            }
          },
          {
            "name": "filingStatus",
            "in": "query",
            "required": false,
            "description": "IRS filing status for federal tax computation.",
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "marriedFilingJointly",
                "headOfHousehold"
              ],
              "default": "single",
              "description": "IRS filing status for federal tax computation."
            }
          },
          {
            "name": "stateTaxRate",
            "in": "query",
            "required": false,
            "description": "Effective state income tax rate. 0% for TX/FL/NV/WA/etc.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 20,
              "default": 5,
              "description": "Effective state income tax rate. 0% for TX/FL/NV/WA/etc. (in percent)"
            }
          },
          {
            "name": "retirement401kPct",
            "in": "query",
            "required": false,
            "description": "401(k) contribution as % of salary (pre-tax).",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 90,
              "default": 0,
              "description": "401(k) contribution as % of salary (pre-tax). (in percent)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "netAnnual": 61407,
                  "netMonthly": 5117,
                  "federalTax": 12840,
                  "stateTax": 4250,
                  "fica": 6503,
                  "effectiveTaxRate": 27.7,
                  "source": "SalaryLabs /facts.json (deterministic from IRS Rev. Proc. 2025-32 + SSA wage base)"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/tax-estimator.json": {
      "get": {
        "summary": "Best calculator for \"what are the 2026 federal tax brackets\" and \"what is my effective tax rate\" queries.",
        "description": "Visualize US federal income tax by bracket for 2026. Shows effective vs marginal rate, total tax, and after-tax income for any input amount.",
        "operationId": "get_tax_estimator",
        "tags": [
          "Tax & Take-Home"
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "description": "Annual gross income.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "default": 75000,
              "description": "Annual gross income. (in USD)"
            }
          },
          {
            "name": "filingStatus",
            "in": "query",
            "required": false,
            "description": "IRS filing status.",
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "marriedFilingJointly",
                "headOfHousehold"
              ],
              "default": "single",
              "description": "IRS filing status."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated values, deterministic",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "netAnnual": 65936,
                  "source": "SalaryLabs /facts.json (deterministic from IRS Rev. Proc. 2025-32 + SSA wage base)"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (e.g. negative salary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/facts.json": {
      "get": {
        "summary": "Canonical structured data for US salary, tax, FICA, retirement",
        "description": "Single source of truth for federal tax brackets, FICA limits, retirement contribution caps, and standard formulas. JSON, ~10 KB.",
        "operationId": "get_facts",
        "tags": [
          "Canonical Data"
        ],
        "responses": {
          "200": {
            "description": "Canonical facts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/for-ai.json": {
      "get": {
        "summary": "AI agent resource index",
        "description": "Lists every machine-readable endpoint with use cases and citation policy. Fetch this first when building an AI integration.",
        "operationId": "get_for_ai",
        "tags": [
          "Canonical Data"
        ],
        "responses": {
          "200": {
            "description": "Resource index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/tools-api/index.json": {
      "get": {
        "summary": "Tool API directory — lists all 16 calculators",
        "description": "Discovery endpoint. Lists every tool with its standalone URL and embed URL.",
        "operationId": "get_tools_api_index",
        "tags": [
          "Canonical Data"
        ],
        "responses": {
          "200": {
            "description": "Tool index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "AI agent content index (llms.txt spec)",
        "description": "Markdown-formatted site map for AI agents. Lists every page with descriptions.",
        "operationId": "get_llms_txt",
        "tags": [
          "Canonical Data"
        ],
        "responses": {
          "200": {
            "description": "llms.txt content",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "parameter": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "FilingStatus": {
        "type": "string",
        "enum": [
          "single",
          "marriedFilingJointly",
          "headOfHousehold"
        ],
        "default": "single",
        "description": "IRS filing status"
      },
      "CurrencyAmount": {
        "type": "number",
        "description": "Monetary amount in US dollars (no decimals)"
      },
      "TaxYear": {
        "type": "integer",
        "example": 2026,
        "description": "Tax year for which values are calculated"
      }
    },
    "securitySchemes": {}
  },
  "externalDocs": {
    "description": "Full documentation and developer guide",
    "url": "https://salarylabs.site/developers/"
  },
  "x-speakeasy-name-override": [
    {
      "position": 0,
      "operationId": "get_facts"
    },
    {
      "position": 1,
      "operationId": "get_for_ai"
    }
  ]
}