{ "openapi": "3.1.0", "info": { "title": "Pascaline API", "version": "2026.1", "description": "Statutes and tables in, dollars out. Same input, same answer, every time. No LLM anywhere in the calculation path. Request bodies are generated from the live Zod schemas; the 200 response is the shared envelope. One endpoint per API is documented here." }, "servers": [ { "url": "https://pascaline.io" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Format: keyId.secret" } } }, "security": [ { "ApiKey": [] } ], "paths": { "/estate/calculate-state-tax": { "post": { "summary": "State Estate & Inheritance Tax", "description": "State estate tax for 12 states + DC and inheritance tax for 6 states, with correct Massachusetts / Oregon full-cliff and New York 105% cliff handling, state QTIP elections, and per-beneficiary inheritance tax.", "tags": [ "Estate Planning Suite" ], "operationId": "state_estate_tax", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "description": "2-letter state code (e.g. MA, NY, OR, MD)", "type": "string", "minLength": 2, "maxLength": 2 }, "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year of death (2026 supported)" }, "gross_estate": { "type": "number", "minimum": 0, "description": "Gross estate value in dollars" }, "marital_deduction_claimed": { "default": 0, "description": "Amount passing to spouse outright", "type": "number", "minimum": 0 }, "state_qtip_election": { "default": 0, "description": "Amount in a state-only QTIP trust", "type": "number", "minimum": 0 }, "bypass_trust_amount": { "default": 0, "description": "Amount in a bypass/credit shelter trust", "type": "number", "minimum": 0 }, "prior_taxable_gifts": { "default": 0, "description": "Completed lifetime gifts excluded from the state taxable estate", "type": "number", "minimum": 0 }, "filing_status": { "default": "single", "type": "string", "enum": [ "single", "married" ] }, "beneficiaries": { "default": [], "description": "For states with inheritance tax: who receives what", "type": "array", "items": { "type": "object", "properties": { "relationship": { "type": "string", "enum": [ "spouse", "child", "grandchild", "parent", "sibling", "niece_nephew", "unrelated" ], "description": "Beneficiary's relationship to the decedent" }, "inheritance_amount": { "type": "number", "minimum": 0, "description": "Amount passing to this beneficiary" } }, "required": [ "relationship", "inheritance_amount" ] } } }, "required": [ "state", "tax_year", "gross_estate" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_state_estate_tax" ] } }, "/estate/calculate-federal-tax": { "post": { "summary": "Federal Estate Tax & Portability", "description": "Federal estate tax with unified-credit and portability (DSUE) mechanics under the permanent $15M exemption, plus the state estate tax for the domicile state.", "tags": [ "Estate Planning Suite" ], "operationId": "federal_estate_tax", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "gross_estate": { "type": "number", "minimum": 0, "description": "Total fair market value of all assets, including life insurance and retirement accounts" }, "deductions": { "default": { "marital_deduction": 0, "charitable_deduction": 0, "debts_and_expenses": 0 }, "type": "object", "properties": { "marital_deduction": { "default": 0, "description": "Unlimited for US-citizen spouse", "type": "number", "minimum": 0 }, "charitable_deduction": { "default": 0, "type": "number", "minimum": 0 }, "debts_and_expenses": { "default": 0, "type": "number", "minimum": 0 } } }, "prior_taxable_gifts": { "default": 0, "description": "Adjusted taxable gifts — ADDED to the tax base per IRC §2001(b)", "type": "number", "minimum": 0 }, "dsue_amount": { "default": 0, "description": "Deceased spouse's unused exclusion, if portability was elected", "type": "number", "minimum": 0 }, "state_of_domicile": { "description": "2-letter state code where the decedent was domiciled", "type": "string", "minLength": 2, "maxLength": 2 }, "decedent_year_of_death": { "default": 2026, "description": "Year of death (2026 supported)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "surviving_spouse": { "default": false, "description": "Include the portability/DSUE section (also inferred from a marital deduction)", "type": "boolean" } }, "required": [ "gross_estate", "state_of_domicile" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_estate_tax" ] } }, "/inherited-ira/schedule": { "post": { "summary": "Inherited IRA RMD Schedule", "description": "Inherited IRA distribution schedules under the July 2024 final regulations — EDB stretch, the minor-child rule, and the annual-RMD-within-the-10-year-window trap that most tools miss.", "tags": [ "Estate Planning Suite" ], "operationId": "inherited_ira_rmd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "decedent": { "type": "object", "properties": { "birth_year": { "type": "integer", "minimum": 1880, "maximum": 2100 }, "death_year": { "type": "integer", "minimum": 2020, "maximum": 2100 }, "death_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "account_type": { "type": "string", "enum": [ "traditional_ira", "roth_ira", "401k", "403b", "sep_ira", "simple_ira" ] }, "rbd_reached": { "type": "boolean", "description": "Whether the decedent had reached the Required Beginning Date (April 1 after the year turning 73)" } }, "required": [ "birth_year", "death_year", "account_type", "rbd_reached" ] }, "beneficiary": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spouse", "non_spouse", "trust", "estate", "charity" ] }, "edb_category": { "description": "Eligible designated beneficiary category, if claimed", "anyOf": [ { "type": "string", "enum": [ "surviving_spouse", "minor_child", "disabled", "chronically_ill", "within_10_years_of_age" ] }, { "type": "null" } ] }, "birth_year": { "type": "integer", "minimum": 0, "maximum": 2100, "description": "0 for non-individuals (estate/charity)" }, "relationship": { "type": "string" } }, "required": [ "type", "birth_year" ] }, "account_balance_at_year_end": { "type": "number", "minimum": 0, "description": "Balance at December 31 of the year prior to the first distribution year" }, "inheritance_year": { "type": "integer", "minimum": 2020, "maximum": 2100 }, "assumed_annual_growth_rate": { "default": 0.06, "type": "number", "minimum": -0.5, "maximum": 0.5 } }, "required": [ "decedent", "beneficiary", "account_balance_at_year_end", "inheritance_year" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_inherited_ira_schedule" ] } }, "/gift-tax/optimize-annual-gifts": { "post": { "summary": "Gift Tax Annual Exclusion Optimizer", "description": "Annual exclusion capacity, §2503(e) medical/tuition exclusions, 529 five-year front-loading, Crummey trust 5&5 and hanging-power analysis, and the separate GST exclusion.", "tags": [ "Estate Planning Suite" ], "operationId": "gift_tax_exclusion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "donors": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "split_gift_consent": { "default": false, "type": "boolean" } } } }, "donees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "relationship": { "default": "non_skip", "type": "string", "enum": [ "child", "grandchild", "other_skip", "non_skip" ] }, "planned_cash_gift": { "default": 0, "type": "number", "minimum": 0 }, "education_costs_direct": { "default": 0, "description": "Tuition paid DIRECTLY to the institution (§2503(e))", "type": "number", "minimum": 0 }, "total_education_costs": { "description": "Total education cost incl. room/board — excess over direct tuition does not qualify", "type": "number", "minimum": 0 }, "medical_costs_direct": { "default": 0, "description": "Medical paid DIRECTLY to the provider (§2503(e))", "type": "number", "minimum": 0 } } } }, "trust_contributions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "trust_type": { "default": "other", "type": "string", "enum": [ "ilit", "gst_trust", "education_trust", "other" ] }, "trust_corpus": { "type": "number", "minimum": 0 }, "crummey_beneficiary_count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "contribution_amount": { "type": "number", "minimum": 0 }, "annual_premium": { "default": 0, "type": "number", "minimum": 0 }, "has_skip_person_beneficiaries": { "default": false, "type": "boolean" }, "gst_qualified": { "type": "boolean" } }, "required": [ "trust_corpus", "crummey_beneficiary_count", "contribution_amount" ] } }, "contributions_529": { "default": [], "type": "array", "items": { "type": "object", "properties": { "donee_name": { "type": "string" }, "contribution_amount": { "type": "number", "minimum": 0 }, "prior_front_loads_this_beneficiary": { "default": 0, "type": "number", "minimum": 0 }, "donor_health_concerns": { "default": false, "type": "boolean" } }, "required": [ "contribution_amount" ] } }, "prior_gifts_ytd": { "default": 0, "type": "number", "minimum": 0 }, "lifetime_exemption_used": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "tax_year", "donors", "donees" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "optimize_annual_gifts" ] } }, "/estate/calculate-grat": { "post": { "summary": "GRAT / CLAT / SLAT Trust Calculator", "description": "GRAT annuity and zero-out math, CLAT charitable deductions, and SLAT analysis using the §7520 rate and Rev Proc 2019-44 annuity factors.", "tags": [ "Estate Planning Suite" ], "operationId": "grat_grut", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trust_type": { "type": "string", "enum": [ "grat", "clat", "slat_analysis" ] }, "transfer_year": { "type": "integer", "minimum": 2020, "maximum": 2100 }, "transfer_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Determines which §7520 rate applies" }, "asset_fmv": { "type": "number", "exclusiveMinimum": 0, "description": "Fair market value of assets transferred to the trust" }, "trust_term_years": { "type": "number", "exclusiveMinimum": 0, "maximum": 99 }, "annuity_payment": { "description": "Annual annuity retained/paid; omit to compute the zero-out amount", "type": "number", "exclusiveMinimum": 0 }, "payment_frequency": { "default": "annual", "type": "string", "enum": [ "annual", "semiannual", "quarterly", "monthly" ] }, "assumed_return_rate": { "description": "Optional: project trust value at term end", "type": "number", "minimum": -0.5, "maximum": 1 }, "section_7520_rate_override": { "description": "Decimal rate (e.g. 0.046) for months not in the bundled table", "type": "number", "exclusiveMinimum": 0, "maximum": 0.3 }, "prior_gifts_used": { "default": 0, "description": "SLAT: lifetime exemption already used", "type": "number", "minimum": 0 }, "projected_growth_rate": { "default": 0.06, "type": "number", "minimum": -0.5, "maximum": 1 }, "years_to_estate": { "default": 20, "type": "integer", "minimum": 1, "maximum": 80 }, "grantor_has_access_to_income": { "default": false, "type": "boolean" }, "spouse_has_reciprocal_slat": { "default": false, "type": "boolean" } }, "required": [ "trust_type", "transfer_year", "transfer_month", "asset_fmv", "trust_term_years" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_grat" ] } }, "/estate/optimize-qtip-election": { "post": { "summary": "QTIP / QDOT Marital Trust Optimizer", "description": "Grid-search the QTIP election fraction to minimize combined estate tax across both spouses' deaths — robust to cliff-state non-monotonicity — with DSUE portability and QDOT analysis for non-citizen spouses.", "tags": [ "Estate Planning Suite" ], "operationId": "qtip_marital_trust", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "first_spouse": { "type": "object", "properties": { "gross_estate": { "type": "number", "minimum": 0 }, "prior_gifts": { "default": 0, "type": "number", "minimum": 0 }, "state_of_domicile": { "type": "string", "minLength": 2, "maxLength": 2 }, "year_of_death": { "default": 2026, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "gross_estate", "state_of_domicile" ] }, "surviving_spouse": { "type": "object", "properties": { "current_assets": { "type": "number", "minimum": 0, "description": "Assets excluding the inherited QTIP" }, "expected_additional_years": { "default": 15, "type": "integer", "minimum": 1, "maximum": 60 }, "assumed_return_rate": { "default": 0.06, "type": "number", "minimum": -0.5, "maximum": 1 }, "state_of_domicile": { "description": "Defaults to the first spouse's domicile", "type": "string", "minLength": 2, "maxLength": 2 }, "non_citizen": { "default": false, "description": "Triggers the QDOT (§2056A) analysis", "type": "boolean" }, "annual_qdot_principal_distribution": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "current_assets" ] }, "qtip_trust_assets": { "type": "number", "exclusiveMinimum": 0 }, "use_portability": { "default": true, "type": "boolean" }, "discount_rate": { "default": 0.03, "type": "number", "minimum": 0, "maximum": 0.5 } }, "required": [ "first_spouse", "surviving_spouse", "qtip_trust_assets" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_optimal_qtip_election" ] } }, "/ss/optimize-filing-strategy": { "post": { "summary": "Social Security Filing Strategy", "description": "Optimizes claiming ages across a couple using SSA life tables, spousal and survivor benefits, the earnings test, and reduction/credit factors.", "tags": [ "Premium Tax Suite" ], "operationId": "ss_filing_strategy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Parameter year (2026 supported)" }, "primary": { "type": "object", "properties": { "current_age": { "type": "number", "minimum": 18, "maximum": 70, "description": "Primary's current age in years (claiming ages already in the past are excluded)" }, "pia": { "type": "number", "exclusiveMinimum": 0, "description": "Primary Insurance Amount — monthly benefit at full retirement age" }, "fra": { "type": "number", "minimum": 65, "maximum": 67, "description": "Full Retirement Age in years (e.g. 67.0 for those born 1960+, 66.5 for 1957)" }, "gender": { "type": "string", "enum": [ "male", "female" ], "description": "Used to select the SSA Period Life Table mortality column" }, "government_pension": { "default": 0, "description": "Annual government pension amount (WEP/GPO repealed Jan 2025; included for historical analysis only)", "type": "number", "minimum": 0 }, "annual_earnings_if_claimed_before_fra": { "default": 0, "description": "Expected annual work earnings while claiming before FRA (earnings test)", "type": "number", "minimum": 0 } }, "required": [ "current_age", "pia", "fra", "gender" ] }, "spouse": { "description": "Optional — if married or divorced (10+ year marriage)", "type": "object", "properties": { "current_age": { "type": "number", "minimum": 18, "maximum": 70 }, "pia": { "type": "number", "exclusiveMinimum": 0 }, "fra": { "type": "number", "minimum": 65, "maximum": 67 }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "is_divorced_spouse": { "default": false, "description": "True if this person is an ex-spouse (marriage lasted 10+ years, currently divorced). Only the primary's claiming age is optimized; the ex is assumed to claim at their FRA.", "type": "boolean" } }, "required": [ "current_age", "pia", "fra", "gender" ] }, "discount_rate": { "default": 0.02, "description": "Annual real discount rate for NPV calculation", "type": "number", "minimum": 0, "maximum": 0.2 }, "planning_horizon_age": { "default": 95, "description": "Maximum age for NPV projection", "type": "integer", "minimum": 70, "maximum": 119 }, "include_all_strategies": { "default": false, "description": "Return NPV for all 81 strategy combinations (default: top 5 + optimal)", "type": "boolean" } }, "required": [ "tax_year", "primary" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "optimize_ss_filing_strategy" ] } }, "/social-security/estimate": { "post": { "summary": "Social Security PIA Estimator", "description": "Computes the PIA from indexed earnings, bend points, and COLAs, with benefit adjustments for claiming age and spousal/survivor amounts.", "tags": [ "Premium Tax Suite" ], "operationId": "ss_pia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "birth_year": { "type": "integer", "minimum": 1900, "maximum": 2015, "description": "Worker's birth year" }, "birth_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Worker's birth month (1-12)" }, "earnings_history": { "description": "Annual taxable SS earnings by year (optional if using simplified mode)", "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Calendar year of the earnings" }, "earnings": { "type": "number", "minimum": 0, "description": "Annual Social Security covered earnings for the year (capped at the wage base)" } }, "required": [ "year", "earnings" ] } }, "projected_earnings": { "description": "Optional: project constant annual earnings for future years after the last history year", "type": "object", "properties": { "annual": { "type": "number", "minimum": 0, "description": "Assumed annual earnings for future years" }, "through_age": { "type": "number", "minimum": 18, "maximum": 70, "description": "Project earnings through the year the worker reaches this age" } }, "required": [ "annual", "through_age" ] }, "current_annual_income": { "description": "Simplified mode: current annual income (used if earnings_history not provided)", "type": "number", "minimum": 0 }, "years_worked": { "description": "Simplified mode: total years of SS-covered employment to date", "type": "integer", "minimum": 0, "maximum": 60 }, "planned_retirement_age": { "description": "Simplified mode: additional working years are assumed through this age", "type": "number", "minimum": 18, "maximum": 75 }, "claiming_age": { "type": "number", "minimum": 62, "maximum": 70, "description": "Planned SS benefit claim age (62.0 to 70.0)" }, "spouse": { "description": "Optional: spouse birth year, claiming age, and own PIA (if known) for spousal benefit", "type": "object", "properties": { "birth_year": { "type": "integer", "minimum": 1900, "maximum": 2020, "description": "Spouse's birth year" }, "claiming_age": { "type": "number", "minimum": 62, "maximum": 70, "description": "Spouse's planned claiming age for the spousal benefit (62-70)" }, "own_pia_estimate": { "description": "Spouse's own PIA if known (monthly dollars); null/omitted if none", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "birth_year", "claiming_age" ] } }, "required": [ "birth_year", "birth_month", "claiming_age" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "estimate_social_security_benefit" ] } }, "/equity/calculate-tax": { "post": { "summary": "ISO Exercise AMT Calculator", "description": "Form 6251 AMT on ISO exercises with the post-OBBBA exemption phaseout, minimum-tax-credit carryforward, plus NSO/RSU/ESPP and 83(b) analysis.", "tags": [ "Premium Tax Suite" ], "operationId": "iso_amt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "iso", "nso" ] }, "exercise_price": { "type": "number", "minimum": 0, "description": "Strike price per share" }, "current_fmv": { "type": "number", "minimum": 0, "description": "FMV per share at (early) exercise today" }, "exercise_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Early exercise date — 83(b) must be filed within 30 days" }, "vesting_schedule": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "vest_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "shares": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "projected_fmv": { "type": "number", "minimum": 0, "description": "Projected FMV per share at this vest date" } }, "required": [ "vest_date", "shares", "projected_fmv" ] } }, "marginal_ordinary_rate": { "default": 0.37, "description": "Assumed marginal ordinary income rate for NSO income (default 37%)", "type": "number", "minimum": 0, "maximum": 1 }, "amt_rate": { "default": 0.28, "description": "Assumed AMT rate applied to ISO preference income (default 28%)", "type": "number", "minimum": 0, "maximum": 1 }, "discount_rate": { "default": 0, "description": "Annual discount rate for NPV of taxes paid at future vest dates (default 0)", "type": "number", "minimum": 0, "maximum": 0.5 } }, "required": [ "grant_type", "exercise_price", "current_fmv", "exercise_date", "vesting_schedule" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_equity_tax" ] } }, "/qsbs/check": { "post": { "summary": "QSBS §1202 Exclusion", "description": "§1202 qualified small business stock exclusion across the pre- and post-OBBBA eras, seven eligibility gates, per-issuer caps, and a 50-state conformity table.", "tags": [ "Premium Tax Suite" ], "operationId": "qsbs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "company": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "C_CORP", "S_CORP", "LLC", "PARTNERSHIP", "SOLE_PROPRIETORSHIP" ], "description": "Entity type at the time the stock was issued (must be C_CORP for QSBS)" }, "state_of_incorporation": { "description": "2-letter state of incorporation (informational)", "type": "string", "minLength": 2, "maxLength": 2 }, "domestic": { "default": true, "description": "Domestic (US) corporation — §1202 requires a domestic C corporation", "type": "boolean" }, "gross_assets_at_issuance": { "type": "number", "minimum": 0, "description": "Aggregate gross assets immediately AFTER issuance, including proceeds and all subsidiaries" }, "gross_assets_pre_issuance": { "description": "Aggregate gross assets immediately before issuance (optional; also tested against the limit)", "type": "number", "minimum": 0 }, "active_business": { "type": "boolean", "description": "At least 80% of assets used in the active conduct of a qualified trade or business (§1202(e))" }, "qualified_trade_or_business": { "type": "boolean", "description": "Business is NOT one of the §1202(e)(3) excluded types (caller assertion)" }, "excluded_types": { "default": [], "description": "Any §1202(e)(3) excluded business types the company operates in — any entry fails the QTOB gate", "type": "array", "items": { "type": "string", "enum": [ "health", "law", "engineering", "architecture", "accounting", "actuarial_science", "performing_arts", "consulting", "athletics", "financial_services", "brokerage", "banking", "insurance", "financing", "leasing", "investing", "farming", "mining_extraction", "hospitality", "hotel_motel_restaurant", "finance" ] } } }, "required": [ "entity_type", "gross_assets_at_issuance", "active_business", "qualified_trade_or_business" ] }, "stock": { "type": "object", "properties": { "acquisition_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the stock was originally issued/acquired (ISO 8601)" }, "acquisition_price_per_share": { "type": "number", "minimum": 0, "description": "Price paid per share (cash/property/services value) — basis per share" }, "shares_acquired": { "type": "number", "exclusiveMinimum": 0, "description": "Number of shares acquired" }, "acquired_from": { "default": "corporation", "description": "How the holder acquired the stock; gift/inheritance can inherit QSBS status from an original-issue holder", "type": "string", "enum": [ "corporation", "underwriter", "gift", "inheritance", "secondary_market", "other" ] }, "original_issue": { "type": "boolean", "description": "Stock was acquired at original issuance from the corporation (directly or, for gift/inheritance, by the transferor)" } }, "required": [ "acquisition_date", "acquisition_price_per_share", "shares_acquired", "original_issue" ] }, "holder": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "individual", "trust", "estate", "partnership", "s_corporation", "c_corporation" ], "description": "Holder entity type — C corporations are not eligible for §1202" }, "state_of_residence": { "description": "2-letter state of residence for state conformity treatment", "type": "string", "minLength": 2, "maxLength": 2 }, "filing_status": { "default": "single", "description": "Federal filing status — married filing separately halves the per-issuer dollar cap (§1202(b)(3))", "type": "string", "enum": [ "single", "married_filing_jointly", "married_filing_separately", "head_of_household" ] }, "prior_section_1202_exclusions_this_issuer": { "default": 0, "description": "Aggregate eligible gain already taken under §1202 for this issuer in prior years (reduces the cumulative dollar cap)", "type": "number", "minimum": 0 } }, "required": [ "entity_type" ] }, "disposition_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of actual or planned sale (ISO 8601) — required; no clock is consulted" }, "sale_price_total": { "description": "Total sale proceeds for the lot (optional) — enables realized-gain and excluded-gain amounts", "type": "number", "minimum": 0 } }, "required": [ "company", "stock", "holder", "disposition_date" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "check_qsbs_eligibility" ] } }, "/ptet/calculate-benefit": { "post": { "summary": "PTET / SALT Cap Optimizer", "description": "Models the pass-through-entity tax workaround to the SALT cap across 36 states, including the OBBBA cap, the QBI interaction cost, and the New York addback.", "tags": [ "Premium Tax Suite" ], "operationId": "ptet_salt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "filing_status": { "type": "string", "enum": [ "single", "mfj", "mfs", "hoh" ], "description": "Owner's federal filing status (drives the SALT cap)" }, "entity_type": { "type": "string", "enum": [ "s_corp", "partnership" ], "description": "Pass-through entity type" }, "federal_marginal_rate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "Owner's federal marginal income tax rate as a decimal (e.g. 0.37)" }, "owner_qbi_before_ptet": { "type": "number", "minimum": 0, "description": "Owner's QBI from this entity before any PTET deduction" }, "state_income_tax_allocations": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "state": { "description": "2-letter state code (e.g. CA, NY, NJ)", "type": "string", "minLength": 2, "maxLength": 2 }, "state_taxable_income": { "type": "number", "minimum": 0, "description": "Entity income allocated to this state (the PTET base)" }, "owner_existing_salt_deductions": { "default": 0, "description": "Other SALT deductions the owner already has against the federal cap (property tax, other states' income taxes, etc.)", "type": "number", "minimum": 0 } }, "required": [ "state", "state_taxable_income" ] }, "description": "One entry per state where the entity has taxable income" }, "all_owner_consent": { "default": true, "description": "Whether all owners consent to the election (some states require unanimity)", "type": "boolean" }, "include_qbi_interaction": { "default": true, "description": "Model the §199A QBI deduction lost because PTET reduces pass-through income", "type": "boolean" }, "owner_magi": { "description": "Optional: owner's MAGI. If provided, the OBBBA SALT-cap phase-down is applied (cap reduced by 30% of MAGI over $505,000 in 2026, floor $10,000; half for MFS).", "type": "number", "minimum": 0 } }, "required": [ "tax_year", "filing_status", "entity_type", "federal_marginal_rate", "owner_qbi_before_ptet", "state_income_tax_allocations" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_ptet_benefit" ] } }, "/qbi/calculate-deduction": { "post": { "summary": "§199A QBI Deduction", "description": "The §199A qualified business income deduction with the post-OBBBA phase-in ranges, SSTB determination, W-2/UBIA limits, and aggregation benefit.", "tags": [ "Premium Tax Suite" ], "operationId": "qbi_199a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "filing_status": { "type": "string", "enum": [ "single", "mfj", "mfs", "hoh" ] }, "taxable_income": { "type": "number", "description": "Taxable income before the QBI deduction" }, "net_capital_gains_and_qualified_dividends": { "default": 0, "description": "Net capital gain plus qualified dividends (subtracted for the 20%-of-taxable-income cap)", "type": "number", "minimum": 0 }, "businesses": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Unique business name (referenced by aggregation_elections)" }, "qbi": { "type": "number", "description": "Qualified business income (net income/loss from the qualified trade or business, already excluding capital gains, dividends, interest, reasonable compensation paid to an S-corp owner, and guaranteed payments). May be negative (loss)." }, "is_sstb": { "type": "boolean", "description": "Whether this is a Specified Service Trade or Business per Treas. Reg. §1.199A-5. The API cannot infer this from the name — see POST /qbi/sstb-guidance." }, "w2_wages": { "type": "number", "minimum": 0, "description": "W-2 wages (Form W-2 Box 1) allocable to this business — NOT 1099 payments" }, "unadjusted_basis_qualified_property": { "default": 0, "description": "UBIA: unadjusted basis immediately after acquisition of qualified depreciable property", "type": "number", "minimum": 0 }, "entity_type": { "default": "sole_prop", "type": "string", "enum": [ "sole_prop", "s_corp", "partnership", "rental_real_estate" ] }, "rental_hours": { "description": "For rental_real_estate: hours of rental services in the year (Rev. Proc. 2019-38 safe harbor: 250+)", "type": "number", "minimum": 0 }, "qualifies_as_trade_or_business": { "description": "For rental_real_estate: override the 250-hour safe harbor when the rental qualifies via self-rental to a related trade or business or general facts-and-circumstances §162 status", "type": "boolean" }, "materially_participates": { "default": true, "description": "Material participation (§469(h)) — required for the OBBBA $400 minimum-deduction eligibility", "type": "boolean" }, "apply_se_tax_adjustment": { "description": "Reduce QBI by the deductible half of self-employment tax (approximation: qbi × 0.9235 × 15.3% / 2). Defaults to true for sole_prop, false otherwise. Set false if qbi is already net of the SE-tax deduction.", "type": "boolean" } }, "required": [ "name", "qbi", "is_sstb", "w2_wages" ] } }, "aggregation_elections": { "default": [], "description": "Each inner array is a group of business names aggregated under Treas. Reg. §1.199A-4 (pooled QBI, W-2 wages, and UBIA for the wage limitation). SSTBs may not be aggregated.", "type": "array", "items": { "minItems": 2, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "reit_dividends": { "default": 0, "description": "Qualified REIT dividends (separate 20% component, no wage limitation)", "type": "number", "minimum": 0 }, "ptp_income": { "default": 0, "description": "Qualified publicly traded partnership income (separate 20% component; may be negative)", "type": "number" }, "prior_year_qualified_business_loss_carryforward": { "default": 0, "description": "Qualified business loss carried forward from the prior year (treated as a current-year loss)", "type": "number", "minimum": 0 } }, "required": [ "tax_year", "filing_status", "taxable_income" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_qbi_deduction" ] } }, "/international/calculate-ftc": { "post": { "summary": "Foreign Tax Credit Limitation", "description": "The §901/§904 foreign tax credit limitation with category baskets, cross-basket rules, high-tax kickout, and AMT FTC.", "tags": [ "Premium Tax Suite" ], "operationId": "foreign_tax_credit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "filing_status": { "type": "string", "enum": [ "single", "mfj", "mfs", "hoh" ], "description": "Filing status (informational; the §904 limitation formula does not vary by status)" }, "total_us_taxable_income": { "type": "number", "description": "Worldwide US taxable income (Form 1040 line 15). May be <= 0, in which case the FTC limit is 0" }, "total_us_tax_before_credits": { "type": "number", "minimum": 0, "description": "Total US tax before credits" }, "amti": { "default": 0, "description": "Alternative Minimum Taxable Income for AMT FTC calculation (0 = skip AMT FTC)", "type": "number", "minimum": 0 }, "amt_before_credits": { "default": 0, "description": "Tentative minimum tax before credits", "type": "number", "minimum": 0 }, "total_deductions": { "description": "Optional: total deductions, used for the simplified pro-rata §861 allocation when an item has no allocable_deductions. If omitted, unallocated items use net = gross (approximation).", "type": "number", "minimum": 0 }, "us_rate_on_passive_income": { "description": "Optional: US effective rate specifically applicable to passive income, used for the high-tax kickout comparison. Defaults to total_us_tax_before_credits / total_us_taxable_income.", "type": "number", "minimum": 0, "maximum": 1 }, "foreign_income": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "basket": { "type": "string", "enum": [ "passive", "general", "section_901j", "ncti", "branch", "gilti" ], "description": "Form 1116 category: passive, general, section_901j, ncti (accepts legacy alias 'gilti'), or branch" }, "gross_foreign_income": { "type": "number", "minimum": 0, "description": "Gross foreign-source income in this item" }, "allocable_deductions": { "default": 0, "description": "Deductions allocated to this foreign income under §861", "type": "number", "minimum": 0 }, "foreign_taxes_paid": { "type": "number", "minimum": 0, "description": "Foreign income taxes paid or accrued on this item" }, "treaty_rate_applied": { "description": "If a treaty reduced withholding, the treaty rate applied as a decimal (e.g. 0.15). Foreign tax above gross_foreign_income × treaty rate is not creditable.", "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "basket", "gross_foreign_income", "foreign_taxes_paid" ] }, "description": "Foreign-source income items by basket" }, "prior_year_carryforwards": { "description": "Unused FTC carryforward per basket from prior years (stateless: caller tracks by basket and year)", "default": {}, "type": "object", "properties": { "passive": { "default": 0, "type": "number", "minimum": 0 }, "general": { "default": 0, "type": "number", "minimum": 0 }, "section_901j": { "default": 0, "type": "number", "minimum": 0 }, "ncti": { "default": 0, "description": "Accepted for spec compatibility but NOT credited: §904(c) denies NCTI-basket carryovers", "type": "number", "minimum": 0 }, "branch": { "default": 0, "type": "number", "minimum": 0 } } } }, "required": [ "tax_year", "filing_status", "total_us_taxable_income", "total_us_tax_before_credits", "foreign_income" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_foreign_tax_credit" ] } }, "/tax-credit/calculate-rd-credit": { "post": { "summary": "R&D Tax Credit (§41)", "description": "The §41 research credit under the ASC and regular methods, the §280C reduced election, and the payroll-tax offset for pre-revenue startups.", "tags": [ "Premium Tax Suite" ], "operationId": "rd_tax_credit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "entity_type": { "type": "string", "enum": [ "c_corp", "s_corp", "partnership", "sole_prop" ], "description": "Entity type; affects §280C guidance and sole-proprietor wage notes" }, "years_of_gross_receipts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of years the entity has had gross receipts (for startup payroll election eligibility)" }, "current_year_gross_receipts": { "type": "number", "minimum": 0, "description": "Current-year gross receipts" }, "current_year_qres": { "type": "object", "properties": { "wages": { "default": 0, "description": "W-2 wages for employees in qualified research activities", "type": "number", "minimum": 0 }, "supplies": { "default": 0, "description": "Tangible supplies used in qualified research (not capital expenditures)", "type": "number", "minimum": 0 }, "contract_research": { "default": 0, "description": "Third-party contract research payments, gross (65% qualifies per §41(b)(3))", "type": "number", "minimum": 0 } }, "description": "Current-year qualified research expenditure components" }, "prior_year_qres": { "default": [], "description": "Prior 3 years QREs for ASC calculation; omit years with no QRE activity", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "year_offset": { "type": "integer", "minimum": 1, "maximum": 3, "description": "1 = prior year, 2 = 2 years ago, 3 = 3 years ago" }, "qres": { "type": "number", "minimum": 0, "description": "Total QREs for that prior year" } }, "required": [ "year_offset", "qres" ] } }, "prior_year_gross_receipts": { "default": [], "description": "Prior 4 years gross receipts for Regular Credit Method base amount", "maxItems": 4, "type": "array", "items": { "type": "number", "minimum": 0 } }, "fixed_base_percentage": { "description": "Historical 1984-1988 QRE/gross-receipts ratio as a decimal (statutory max 0.16); null for startups using the phase-in", "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "years_with_both_qre_and_receipts": { "description": "For startup phase-in: years the company has had both QREs and gross receipts", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "include_regular_method": { "default": true, "type": "boolean" }, "section_280c_election": { "default": "reduced_89pct", "type": "string", "enum": [ "full_credit", "reduced_89pct" ] }, "prior_year_carryforward": { "default": 0, "description": "Unused §41 credit carried forward from prior years (DEEP-DIVE Step 6; caller tracks the balance — 20-year carryforward under §39)", "type": "number", "minimum": 0 } }, "required": [ "tax_year", "entity_type", "years_of_gross_receipts", "current_year_gross_receipts", "current_year_qres" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_rd_tax_credit" ] } }, "/ira/form-8606": { "post": { "summary": "Form 8606 / Backdoor Roth", "description": "Nondeductible IRA basis, the pro-rata rule, backdoor and mega-backdoor Roth analysis, and the conversion-optimization decision.", "tags": [ "Retirement & International Suite" ], "operationId": "form_8606", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tax year (2026 supported)" }, "filing_status": { "default": "single", "description": "Filing status — used only by the Roth conversion bracket optimizer", "type": "string", "enum": [ "single", "mfj", "mfs", "hoh" ] }, "age": { "description": "Optional: taxpayer age at year end, used for the age-50 catch-up contribution check", "type": "integer", "minimum": 0, "maximum": 120 }, "prior_total_basis": { "type": "number", "minimum": 0, "description": "Line 14 from prior year Form 8606 (cumulative nondeductible basis carried forward)" }, "nondeductible_contributions_this_year": { "default": 0, "description": "Nondeductible traditional IRA contributions for this tax year (Form 8606 line 1)", "type": "number", "minimum": 0 }, "all_traditional_ira_fmv_dec31": { "type": "number", "minimum": 0, "description": "Total FMV of ALL traditional, SEP, and SIMPLE IRAs at December 31 (Form 8606 line 6) — every account at every institution, even ones not contributed to this year" }, "ira_accounts": { "description": "Optional itemized list of every traditional/SEP/SIMPLE IRA. If provided, the sum is cross-checked against all_traditional_ira_fmv_dec31 (pro-rata aggregation guard)", "type": "array", "items": { "type": "object", "properties": { "label": { "description": "Optional account label (e.g. 'Fidelity rollover IRA')", "type": "string" }, "fmv_dec31": { "type": "number", "minimum": 0, "description": "This account's fair market value at December 31" } }, "required": [ "fmv_dec31" ] } }, "roth_conversions_this_year": { "default": 0, "description": "Amounts converted from traditional/SEP/SIMPLE IRA to Roth IRA this year (Form 8606 line 8)", "type": "number", "minimum": 0 }, "distributions_this_year": { "default": 0, "description": "Traditional/SEP/SIMPLE IRA distributions this year (Form 8606 line 7), excluding conversions, rollovers, QCDs, and recharacterizations", "type": "number", "minimum": 0 }, "recharacterized_conversion_amount": { "default": 0, "description": "Roth conversion amount the caller intends to recharacterize — NOT allowed after 2017 (TCJA §13611); any value > 0 triggers a warning and is ignored in the calculation", "type": "number", "minimum": 0 }, "current_taxable_income": { "description": "Current-year taxable income BEFORE any recommended conversion — enables the bracket-fill optimizer", "type": "number", "minimum": 0 }, "current_marginal_rate": { "description": "Current marginal tax rate as a decimal (e.g. 0.24)", "type": "number", "minimum": 0, "maximum": 1 }, "projected_retirement_marginal_rate": { "description": "Projected marginal tax rate in retirement as a decimal (e.g. 0.32)", "type": "number", "minimum": 0, "maximum": 1 }, "roth_contribution_5yr_clock_started": { "description": "Year of the FIRST Roth IRA contribution ever made (starts the qualified-distribution 5-year clock)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "conversion_years": { "description": "Years of prior Roth conversions — each starts its own 5-year penalty-recapture clock", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "after_tax_401k_prior_basis": { "default": 0, "description": "After-tax 401(k) basis carried in from prior years (mega backdoor Roth)", "type": "number", "minimum": 0 }, "after_tax_401k_contributions": { "default": 0, "description": "After-tax (non-Roth) 401(k) contributions this year, for mega backdoor Roth", "type": "number", "minimum": 0 }, "after_tax_401k_earnings": { "default": 0, "description": "Earnings attributable to the after-tax 401(k) subaccount (taxable when converted)", "type": "number", "minimum": 0 }, "in_plan_conversion_this_year": { "default": 0, "description": "After-tax 401(k) amount converted in-plan to Roth 401(k) or rolled to Roth IRA this year", "type": "number", "minimum": 0 }, "inherited_ira": { "description": "Optional inherited traditional IRA with basis — tracked on a SEPARATE Form 8606, never mixed with the beneficiary's own IRA pro-rata calculation", "type": "object", "properties": { "fmv_dec31": { "type": "number", "minimum": 0, "description": "Inherited traditional IRA FMV at December 31" }, "basis": { "type": "number", "minimum": 0, "description": "Basis inherited from the decedent (their Form 8606 line 14)" }, "distributions_this_year": { "default": 0, "description": "Distributions taken from the inherited IRA this year", "type": "number", "minimum": 0 } }, "required": [ "fmv_dec31", "basis" ] } }, "required": [ "tax_year", "prior_total_basis", "all_traditional_ira_fmv_dec31" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_ira_basis_and_conversion", "analyze_backdoor_roth" ] } }, "/pension/lump-sum-comparison": { "post": { "summary": "Pension Lump Sum vs Annuity", "description": "Compares a pension lump sum against the annuity using SSA mortality, break-even ages, and the PBGC guarantee cap.", "tags": [ "Retirement & International Suite" ], "operationId": "pension_lumpsum", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "participant_age": { "type": "integer", "minimum": 40, "maximum": 100, "description": "Participant's age (whole years) when payments would start" }, "participant_sex": { "type": "string", "enum": [ "male", "female" ], "description": "Sex for SSA period life table mortality lookup" }, "monthly_annuity_single_life": { "type": "number", "exclusiveMinimum": 0, "description": "Monthly payment under the single life annuity option" }, "monthly_annuity_joint_50": { "description": "Optional: monthly payment under the joint-and-50% survivor option (requires spouse_age/spouse_sex)", "type": "number", "exclusiveMinimum": 0 }, "monthly_annuity_joint_100": { "description": "Optional: monthly payment under the joint-and-100% survivor option (requires spouse_age/spouse_sex)", "type": "number", "exclusiveMinimum": 0 }, "lump_sum_offer": { "type": "number", "exclusiveMinimum": 0, "description": "One-time lump sum offer in lieu of the annuity" }, "assumed_investment_return": { "default": 0.06, "description": "Annual nominal return assumed on an invested lump sum; also the annuity discount rate (default 0.06)", "type": "number", "minimum": -0.05, "maximum": 0.25 }, "risk_free_rate": { "description": "Optional: annual risk-free (Treasury) rate. If provided, each option also returns its PV at this rate. Caller-supplied because Treasury yields are external monthly data (no bundled default).", "type": "number", "minimum": -0.02, "maximum": 0.15 }, "assumed_inflation": { "default": 0.03, "description": "Annual inflation assumption used for the real (inflation-adjusted) NPV (default 0.03)", "type": "number", "minimum": -0.02, "maximum": 0.15 }, "annual_cola_rate": { "default": 0, "description": "Annual cost-of-living adjustment applied to the pension payment (default 0 = flat nominal pension)", "type": "number", "minimum": 0, "maximum": 0.1 }, "pension_is_pbgc_insured": { "default": true, "description": "Whether the plan is PBGC-insured (most private-sector DB plans)", "type": "boolean" }, "pbgc_max_guarantee_at_65_override": { "description": "Optional: PBGC monthly maximum guarantee for a single life annuity at age 65, overriding the bundled figure (use for years not bundled or once PBGC publishes an updated cap)", "type": "number", "exclusiveMinimum": 0 }, "current_marginal_tax_rate": { "description": "Marginal ordinary income tax rate applied to annuity payments (decimal)", "type": "number", "minimum": 0, "maximum": 0.6 }, "retirement_marginal_tax_rate": { "description": "Marginal tax rate assumed on eventual IRA withdrawals of the rolled-over lump sum (decimal)", "type": "number", "minimum": 0, "maximum": 0.6 }, "spouse_age": { "description": "Spouse's age (whole years); required if a joint annuity option is provided", "type": "integer", "minimum": 18, "maximum": 100 }, "spouse_sex": { "description": "Spouse's sex; required if a joint annuity option is provided", "type": "string", "enum": [ "male", "female" ] }, "health_adjustment": { "default": "average", "description": "Optional longevity adjustment vs. the US-average SSA table: below_average shifts death probabilities +15%, above_average -15% (spec FM1 mitigation)", "type": "string", "enum": [ "average", "below_average", "above_average" ] } }, "required": [ "participant_age", "participant_sex", "monthly_annuity_single_life", "lump_sum_offer" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "compare_pension_lump_sum" ] } }, "/ssdi/estimate-benefit": { "post": { "summary": "SSDI Benefit Estimator", "description": "Social Security Disability Insurance benefits with insured-status work credits, the disability-freeze computation, family maximum, and the workers-comp offset.", "tags": [ "Retirement & International Suite" ], "operationId": "ssdi", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "birth_year": { "type": "integer", "minimum": 1900, "maximum": 2020, "description": "Worker's birth year" }, "birth_month": { "default": 1, "description": "Worker's birth month (1-12); defaults to January if unknown", "type": "integer", "minimum": 1, "maximum": 12 }, "disability_onset_year": { "type": "integer", "minimum": 1951, "maximum": 2100, "description": "Year the disability began (alleged onset date year)" }, "disability_onset_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month the disability began (1-12)" }, "earnings_history": { "minItems": 1, "maxItems": 80, "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Calendar year of the earnings" }, "earnings": { "type": "number", "minimum": 0, "description": "Annual Social Security covered earnings for the year" } }, "required": [ "year", "earnings" ] }, "description": "Annual SS-covered earnings by year (ideally age 22 through disability onset)" }, "blind": { "default": false, "description": "Statutorily blind (higher SGA; recent-work test waived)", "type": "boolean" }, "application_year": { "type": "integer", "minimum": 1951, "maximum": 2100, "description": "Year the SSDI application is (or will be) filed" }, "workers_comp_monthly": { "default": 0, "description": "Monthly workers' compensation benefit, if any", "type": "number", "minimum": 0 }, "dependents": { "default": [], "description": "Dependents potentially eligible for auxiliary benefits (spouse and/or children)", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spouse", "child" ], "description": "Dependent type" }, "age": { "type": "integer", "minimum": 0, "maximum": 120, "description": "Dependent's current age in years" } }, "required": [ "type", "age" ] } }, "state": { "description": "Two-letter state code of the workers' compensation plan (used only for the reverse-offset state check)", "type": "string", "minLength": 2, "maxLength": 2 }, "current_monthly_earnings": { "description": "Current gross monthly work earnings, for the SGA threshold check", "type": "number", "minimum": 0 } }, "required": [ "birth_year", "disability_onset_year", "disability_onset_month", "earnings_history", "application_year" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "estimate_ssdi_benefit", "check_ssdi_work_credits" ] } }, "/canada/retirement-benefit": { "post": { "summary": "CPP + OAS (Canada)", "description": "Canada Pension Plan and Old Age Security estimates with the CPP enhancement, deferral adjustments, the OAS clawback, and GIS.", "tags": [ "Retirement & International Suite" ], "operationId": "cpp_oas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tax_year": { "default": 2026, "description": "Parameter year for rates/ceilings (2026 supported)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "birth_year": { "type": "integer", "minimum": 1900, "maximum": 2010, "description": "Year of birth" }, "birth_month": { "description": "Month of birth, 1-12 (informational; whole-month precision comes from planned_retirement_age)", "type": "integer", "minimum": 1, "maximum": 12 }, "planned_retirement_age": { "type": "number", "minimum": 60, "maximum": 70, "description": "Age when CPP starts (60-70). OAS cannot start before 65; fractional ages are rounded to whole months" }, "cpp_contributions": { "type": "object", "properties": { "years_of_contribution": { "type": "integer", "minimum": 0, "maximum": 52, "description": "Total years with CPP contributions (age 18 to retirement; max 52)" }, "average_annual_pensionable_earnings": { "type": "number", "minimum": 0, "description": "Average annual pensionable earnings (CAD) over the contribution years; capped at the YMPE for the base CPP calculation" }, "cpp2_contributions_since_2019": { "default": false, "description": "True if the worker contributed under the enhanced CPP (2019+); enables both additional components", "type": "boolean" }, "child_rearing_dropout_years": { "default": 0, "description": "Years excluded under the child-rearing provision (caring for a child under 7)", "type": "integer", "minimum": 0, "maximum": 40 }, "disability_dropout_years": { "default": 0, "description": "Years excluded while receiving a CPP disability pension", "type": "integer", "minimum": 0, "maximum": 40 } }, "required": [ "years_of_contribution", "average_annual_pensionable_earnings" ] }, "oas_residency": { "type": "object", "properties": { "years_resident_in_canada_after_18": { "type": "integer", "minimum": 0, "maximum": 82, "description": "Years of Canadian residence after age 18 (40+ = full OAS; minimum 10 for eligibility)" } }, "required": [ "years_resident_in_canada_after_18" ] }, "income_for_gis": { "description": "Annual income (CAD, excluding OAS/GIS) used for the GIS eligibility test AND the OAS clawback check. Null/omitted = not assessed", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "annual_income_for_gis_check": { "description": "Alias for income_for_gis (the MCP schema field name in the spec); income_for_gis wins if both are set", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "birth_year", "planned_retirement_age", "cpp_contributions", "oas_residency" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "estimate_canadian_retirement_benefit" ] } }, "/australia/superannuation/contributions": { "post": { "summary": "Australian Superannuation", "description": "Australian superannuation contributions with the 12% SG rate, concessional and non-concessional caps, bring-forward rules, Division 293, and co-contributions.", "tags": [ "Retirement & International Suite" ], "operationId": "aus_super", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "financial_year_start": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Financial year start year, e.g. 2025 for FY2025-26 (1 July 2025 – 30 June 2026)" }, "age_at_july_1": { "type": "integer", "minimum": 0, "maximum": 120, "description": "Age at 1 July of the financial year" }, "tsb_prior_june_30": { "type": "number", "minimum": 0, "description": "Total Super Balance at the prior 30 June (AUD)" }, "concessional_contributions_ytd": { "default": 0, "description": "Concessional (before-tax: employer SG + salary sacrifice + deductible personal) contributions this FY", "type": "number", "minimum": 0 }, "non_concessional_contributions_ytd": { "default": 0, "description": "Non-concessional (after-tax) contributions this FY", "type": "number", "minimum": 0 }, "prior_year_1_ncc": { "default": 0, "description": "Non-concessional contributions 1 year ago (for bring-forward tracking)", "type": "number", "minimum": 0 }, "prior_year_2_ncc": { "default": 0, "description": "Non-concessional contributions 2 years ago (for bring-forward tracking)", "type": "number", "minimum": 0 }, "income_for_division_293": { "description": "Income for Division 293 purposes: taxable income + reportable fringe benefits + net investment losses + low-tax concessional contributions. Omit to skip the Division 293 check.", "type": "number", "minimum": 0 }, "include_co_contribution_check": { "default": false, "description": "If true, also compute government co-contribution eligibility", "type": "boolean" }, "total_income": { "description": "Extension (not in the spec's MCP schema): total income for the co-contribution test and the excess-CC marginal-rate lookup. Falls back to income_for_division_293 when omitted.", "type": "number", "minimum": 0 }, "unused_concessional_cap_carry_forward": { "default": 0, "description": "Total unused concessional cap carried forward from up to 5 prior financial years (DEEP-DIVE: 'or accept as input'). Only applied when TSB at the prior 30 June < $500,000.", "type": "number", "minimum": 0 }, "bring_forward_years_triggered": { "description": "If a bring-forward period was triggered in a prior year, how many years (2 or 3) it covered. If omitted while prior-year NCCs exceed that year's annual cap, a 3-year period is assumed (noted).", "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "excess_cc_months_outstanding": { "default": 12, "description": "Months used for the approximate shortfall interest charge estimate on excess CC (default 12)", "type": "number", "exclusiveMinimum": 0, "maximum": 60 }, "date_of_birth": { "description": "Optional ISO date of birth; when supplied, preservation age is returned (informational)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "financial_year_start", "age_at_july_1", "tsb_prior_june_30" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_super_contributions" ] } }, "/ada/requirements": { "post": { "summary": "ADA Compliance Requirements", "description": "Deterministic ADA requirements — accessible parking, elevators, routes, ramps, and restrooms — from the 2010 Standards with state-code overlays.", "tags": [ "Compliance & Data Suite" ], "operationId": "ada_compliance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "facility_type": { "type": "string", "enum": [ "office", "retail", "restaurant", "hotel", "medical", "assembly", "educational", "parking_structure", "residential_multifamily", "recreation" ], "description": "Building/facility type" }, "total_square_footage": { "type": "number", "exclusiveMinimum": 0, "description": "Total building square footage across all stories" }, "stories": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Number of stories (mezzanines over 1/3 of the floor area count as stories)" }, "total_parking_spaces": { "description": "Total parking spaces in the parking facility (omit if no parking is provided)", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scope": { "type": "string", "enum": [ "new_construction", "alteration", "addition" ], "description": "Project scope: new_construction, alteration, or addition" }, "state": { "description": "US state code for state-specific overlay (e.g. CA, TX, FL)", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "occupancy_load": { "description": "Maximum occupant capacity per fire code; drives the 44 in corridor width rule at 50+", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "entity_type": { "default": "private", "description": "private = Title III place of public accommodation / commercial facility; public = Title II state or local government facility (the small-building elevator exemption is unavailable to public entities)", "type": "string", "enum": [ "private", "public" ] }, "largest_story_square_footage": { "description": "Square footage of the largest single story. If omitted, per-story area is estimated as total_square_footage / stories for the §206.2.3 elevator exemption test (an assumption noted in the response)", "type": "number", "exclusiveMinimum": 0 }, "is_shopping_center": { "default": false, "description": "True if the building houses five or more sales/rental establishments (disqualifies the elevator exemption)", "type": "boolean" }, "is_qualified_historic": { "default": false, "description": "True if the building is a qualified historic building (alternative minimum requirements may apply to alterations, §202.5)", "type": "boolean" }, "total_drinking_fountains": { "description": "Number of drinking fountains planned/provided; used for the §211 50% wheelchair/standing split", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "facility_type", "total_square_footage", "stories", "scope" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_ada_requirements" ] } }, "/child-support/calculate": { "post": { "summary": "Child Support Calculation", "description": "Child support under the three guideline models (income shares, percentage of income, Melson) for the states whose tables are individually citable; others return an explicit not-loaded rather than a wrong number.", "tags": [ "Compliance & Data Suite" ], "operationId": "child_support", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "description": "US state (2-letter code)", "type": "string", "minLength": 2, "maxLength": 2 }, "tax_year": { "default": 2026, "description": "Guideline parameter year (2026 supported)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "model": { "description": "Optional: expected guideline model. If provided and it does not match the state's actual model, the request is rejected (MODEL_MISMATCH)", "type": "string", "enum": [ "income_shares", "percentage_of_income", "melson" ] }, "children_count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of children covered by the order (1-10)" }, "obligor": { "type": "object", "properties": { "gross_monthly_income": { "type": "number", "minimum": 0, "description": "Obligor's monthly income in the state's guideline income basis (see income_basis in response)" }, "other_child_support_paid": { "default": 0, "description": "Pre-existing court-ordered child support the obligor pays for other children (deducted from income)", "type": "number", "minimum": 0 }, "self_employment_adjustment": { "default": 0, "description": "Self-employment deduction amount per the state's rule (e.g. deductible SE tax); deducted from income", "type": "number", "minimum": 0 } }, "required": [ "gross_monthly_income" ], "description": "The paying parent" }, "obligee": { "type": "object", "properties": { "gross_monthly_income": { "type": "number", "minimum": 0, "description": "Obligee's monthly income in the state's guideline income basis" }, "other_child_support_paid": { "default": 0, "description": "Pre-existing court-ordered child support the obligee pays for other children (deducted from income)", "type": "number", "minimum": 0 } }, "required": [ "gross_monthly_income" ], "description": "The receiving parent" }, "parenting_time": { "description": "Obligor's parenting time (overnights per year)", "default": {}, "type": "object", "properties": { "obligor_overnights_per_year": { "description": "Overnights per year the children spend with the obligor", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 366 }, { "type": "null" } ] }, "schedule_type": { "description": "Informational label, e.g. standard_residential", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "adjustments": { "description": "Childcare / health insurance / extraordinary expense add-ons and who pays them", "default": {}, "type": "object", "properties": { "work_related_childcare_monthly": { "default": 0, "description": "Monthly work-related childcare cost, apportioned by income share", "type": "number", "minimum": 0 }, "obligor_pays_childcare": { "default": false, "description": "True if the obligor pays the childcare cost directly (credited); false = obligee pays (added)", "type": "boolean" }, "health_insurance_premium_monthly": { "default": 0, "description": "Monthly health insurance premium for the children, apportioned by income share", "type": "number", "minimum": 0 }, "obligor_pays_health_insurance": { "default": false, "description": "True if the obligor pays the premium directly (credited); false = obligee pays (added)", "type": "boolean" }, "extraordinary_expenses_monthly": { "default": 0, "description": "Monthly extraordinary expenses (medical, education), apportioned by income share", "type": "number", "minimum": 0 }, "obligor_pays_extraordinary": { "default": false, "description": "True if the obligor pays the extraordinary expenses directly (credited); false = obligee pays (added)", "type": "boolean" } } } }, "required": [ "state", "children_count", "obligor", "obligee" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_child_support" ] } }, "/employment-law/lookup": { "post": { "summary": "Multi-State Employment Law", "description": "50-state + DC employment-law rules (minimum wage, overtime thresholds, paid sick leave, non-compete, salary transparency) as a time series with effective dates and upcoming changes.", "tags": [ "Compliance & Data Suite" ], "operationId": "employment_law", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "description": "Two-letter state code (50 states + DC)" }, "law_type": { "type": "string", "enum": [ "minimum_wage", "overtime_threshold", "paid_sick_leave", "non_compete", "salary_transparency", "pfml", "required_notices", "contractor_classification" ], "description": "Employment law data type. Tier 1 types are loaded; pfml, required_notices, and contractor_classification return NOT_LOADED in this release." }, "as_of_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the rule must be in effect (YYYY-MM-DD). Pure/deterministic API: callers supply the date — typically today. Supported range 2025-01-01 to 2030-12-31." }, "include_upcoming": { "default": true, "description": "Include scheduled future changes (legislated steps and announced adjustments)", "type": "boolean" } }, "required": [ "state", "law_type", "as_of_date" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "get_employment_law", "list_upcoming_changes" ] } }, "/fafsa/sai": { "post": { "summary": "FAFSA Student Aid Index", "description": "The FAFSA Student Aid Index and Pell eligibility under the current Simplified formula — not the retired EFC method most tools still use.", "tags": [ "Compliance & Data Suite" ], "operationId": "fafsa_sai", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "school_year": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "FAFSA award year, e.g. '2026-27'" }, "student": { "type": "object", "properties": { "dependency_status": { "type": "string", "enum": [ "dependent", "independent" ], "description": "Dependent students use Formula A (parents required); independents use Formula B or C" }, "marital_status": { "description": "Independent students only; selects Formula B/C IPA-EEA variants (default unmarried)", "type": "string", "enum": [ "unmarried", "married" ] }, "has_dependents": { "description": "Independent students: dependents other than a spouse (selects Formula C). Defaults from family_size per SAI Guide Table 7 (unmarried >= 2, married >= 3).", "type": "boolean" }, "family_size": { "description": "Independent students: family size including the student (default 1, or 2 if married)", "type": "integer", "minimum": 1, "maximum": 99 }, "state": { "description": "State of legal residence — used ONLY for the Pell poverty-guideline tests (AK / HI / other). The post-Simplification SAI formula has NO state tax allowance.", "type": "string", "maxLength": 40 }, "tax_filing_status": { "description": "Student (and spouse) tax filing status; 'did_not_file' for an independent student triggers Max Pell Indicator 1", "type": "string", "enum": [ "single", "married_filing_jointly", "married_filing_separately", "head_of_household", "qualifying_surviving_spouse", "did_not_file" ] }, "enrollment": { "description": "Informational only — the SAI and scheduled Pell award do not vary by enrollment intensity", "type": "string", "enum": [ "full_time", "three_quarter_time", "half_time", "less_than_half_time" ] }, "grade_level": { "description": "Informational only — not used in the SAI formula", "type": "string", "maxLength": 40 }, "age": { "description": "Student age as of 12/31/2025 (asset protection allowance lookup — $0 at every age for 2026-27)", "type": "integer", "minimum": 13, "maximum": 120 }, "income": { "type": "number", "description": "Student (and spouse, if married) AGI for the prior-prior tax year (2024)" }, "income_earned_from_work": { "description": "Wages/self-employment earnings for the payroll-tax and employment-expense allowances (defaults to max(0, income) with a warning)", "type": "number", "minimum": 0 }, "taxes_paid": { "default": 0, "description": "U.S. federal income tax paid (or foreign equivalent)", "type": "number", "minimum": 0 }, "untaxed_income": { "default": 0, "description": "Other income additions: deductible IRA/Keogh payments, tax-exempt interest, untaxed IRA/pension distributions", "type": "number", "minimum": 0 }, "foreign_income_exclusion": { "default": 0, "type": "number", "minimum": 0 }, "assets": { "default": 0, "description": "Cash, savings, checking, and net worth of investments (excluding primary residence and retirement accounts)", "type": "number", "minimum": 0 }, "business_farm_net_worth": { "default": 0, "description": "Net worth of businesses and/or farms (adjusted via the Table A3/B2/C4 schedule)", "type": "number" }, "child_support_received": { "default": 0, "description": "Annual child support received (an ASSET in the SAI formula; independent students only — a dependent student's goes on the parent side)", "type": "number", "minimum": 0 }, "received_eitc": { "description": "Received the Earned Income Tax Credit (single-parent indicator input)", "type": "boolean" } }, "required": [ "dependency_status", "income" ] }, "parents": { "description": "Required when student.dependency_status is 'dependent'", "type": "object", "properties": { "marital_status": { "description": "Parent married indicator (defaults from filing_status: MFJ/MFS -> married, otherwise unmarried)", "type": "string", "enum": [ "married", "unmarried" ] }, "filing_status": { "description": "Parents' tax filing status; 'did_not_file' triggers Max Pell Indicator 1 (SAI = -1,500)", "type": "string", "enum": [ "single", "married_filing_jointly", "married_filing_separately", "head_of_household", "qualifying_surviving_spouse", "did_not_file" ] }, "household_size": { "type": "integer", "minimum": 2, "maximum": 99, "description": "Family size including the student (drives the income protection allowance)" }, "number_in_college": { "description": "ACCEPTED BUT NOT USED: the FAFSA Simplification Act eliminated the division of the parent contribution by number in college for 2024-25 and later award years", "type": "integer", "minimum": 0, "maximum": 20 }, "agi": { "type": "number", "description": "Parents' AGI for the prior-prior tax year (2024)" }, "income_earned_from_work": { "description": "Parents' combined income earned from work (defaults to max(0, agi) with a warning)", "type": "number", "minimum": 0 }, "taxes_paid": { "default": 0, "description": "Parents' U.S. federal income tax paid", "type": "number", "minimum": 0 }, "untaxed_income": { "default": 0, "description": "Other income additions: deductible IRA/Keogh payments, tax-exempt interest, untaxed IRA/pension distributions", "type": "number", "minimum": 0 }, "foreign_income_exclusion": { "default": 0, "type": "number", "minimum": 0 }, "assets": { "default": 0, "description": "Cash, savings, and checking accounts", "type": "number", "minimum": 0 }, "investment_net_worth": { "default": 0, "description": "Net worth of investments excluding the primary residence (negative treated as zero)", "type": "number" }, "business_net_worth": { "default": 0, "description": "Net worth of businesses and/or farms (adjusted via the Table A3 schedule)", "type": "number" }, "child_support_received": { "default": 0, "description": "Annual child support received (asset line 10)", "type": "number", "minimum": 0 }, "age_of_older_parent": { "description": "Asset protection allowance lookup — $0 at every age in the 2026-27 Table A4", "type": "integer", "minimum": 18, "maximum": 120 }, "received_eitc": { "description": "Parent received the Earned Income Tax Credit (single-parent indicator input)", "type": "boolean" }, "single_parent": { "description": "Explicit single-parent override for the Pell poverty tests (otherwise derived per SAI Guide Table 8)", "type": "boolean" } }, "required": [ "household_size", "agi" ] } }, "required": [ "school_year", "student" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_student_aid_index" ] } }, "/immigration/calculate": { "post": { "summary": "Immigration Points & Eligibility", "description": "Points and eligibility for Canadian Express Entry (CRS + FSW), Australian skilled visas, and the UK Skilled Worker route, from the official grids.", "tags": [ "Compliance & Data Suite" ], "operationId": "immigration_points", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "country": { "type": "string", "enum": [ "CA", "AU", "GB" ], "description": "Destination country" }, "program": { "type": "string", "enum": [ "express_entry_fsw", "express_entry_cec", "express_entry_fst", "skilled_independent_189", "skilled_nominated_190", "skilled_work_regional_491", "uk_skilled_worker" ], "description": "Immigration program to assess" }, "profile": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 16, "maximum": 99, "description": "Applicant age at (assumed) invitation date" }, "education": { "type": "string", "enum": [ "less_than_secondary", "secondary", "one_year_diploma", "two_year_diploma", "bachelors", "two_or_more_bachelors", "masters", "phd" ], "description": "Highest completed education credential" }, "first_official_language_clb": { "description": "Canada: CLB level in the first official language, assumed uniform across all four abilities (single-number simplification from the spec)", "type": "integer", "minimum": 0, "maximum": 12 }, "second_official_language_clb": { "description": "Canada: CLB level in the second official language (uniform across abilities)", "type": "integer", "minimum": 0, "maximum": 12 }, "canadian_work_experience_years": { "default": 0, "description": "Years of skilled (TEER 0-3) work in Canada", "type": "number", "minimum": 0 }, "foreign_work_experience_years": { "default": 0, "description": "Years of skilled work outside Canada", "type": "number", "minimum": 0 }, "noc_teer": { "description": "Canada: TEER category of the primary occupation (0-5); used for CEC language minimums", "type": "integer", "minimum": 0, "maximum": 5 }, "job_offer": { "default": false, "description": "Valid job offer (Canada: LMIA-backed arranged employment; UK: sponsored job offer)", "type": "boolean" }, "provincial_nomination": { "default": false, "description": "Canada: provincial/territorial nomination (+600 CRS)", "type": "boolean" }, "canadian_education": { "default": "none", "description": "Canada: post-secondary credential earned in Canada", "type": "string", "enum": [ "none", "one_two_year", "three_year_plus" ] }, "french_nclc": { "description": "Canada: NCLC level in French (all abilities); NCLC 7+ earns additional CRS points", "type": "integer", "minimum": 0, "maximum": 12 }, "sibling_in_canada": { "default": false, "description": "Canada: sibling in Canada who is a citizen or permanent resident", "type": "boolean" }, "certificate_of_qualification": { "default": false, "description": "Canada: provincial/territorial certificate of qualification in a trade", "type": "boolean" }, "spouse": { "description": "Spouse/partner profile, or null/omitted if single", "anyOf": [ { "type": "object", "properties": { "education": { "type": "string", "enum": [ "less_than_secondary", "secondary", "one_year_diploma", "two_year_diploma", "bachelors", "two_or_more_bachelors", "masters", "phd" ], "description": "Spouse/partner highest completed education" }, "first_official_language_clb": { "default": 0, "description": "Spouse CLB level, assumed uniform across all four abilities", "type": "integer", "minimum": 0, "maximum": 12 }, "canadian_work_experience_years": { "default": 0, "type": "number", "minimum": 0 }, "accompanying": { "default": true, "description": "True if the spouse/partner accompanies the applicant to Canada and is not a Canadian citizen/PR. Non-accompanying (or citizen/PR) spouses score under the single-applicant CRS tables.", "type": "boolean" } }, "required": [ "education" ] }, { "type": "null" } ] }, "au_english": { "description": "Australia: English level — competent (IELTS 6), proficient (IELTS 7), superior (IELTS 8)", "type": "string", "enum": [ "less_than_competent", "competent", "proficient", "superior" ] }, "au_qualification": { "description": "Australia: qualification band; derived from `education` when omitted", "type": "string", "enum": [ "doctorate", "bachelors_or_masters", "diploma_or_trade", "recognized_qualification", "none" ] }, "australian_skilled_employment_years": { "default": 0, "description": "Australia: years of skilled employment in Australia in the last 10 years", "type": "number", "minimum": 0 }, "overseas_skilled_employment_years": { "description": "Australia: years of skilled employment outside Australia in the last 10 years (falls back to foreign_work_experience_years when omitted)", "type": "number", "minimum": 0 }, "australian_study_requirement": { "default": false, "description": "Australia: meets the 2-academic-year Australian study requirement", "type": "boolean" }, "specialist_education": { "default": false, "description": "Australia: masters by research / doctorate in STEM from an Australian institution", "type": "boolean" }, "regional_study": { "default": false, "description": "Australia: study in regional Australia", "type": "boolean" }, "professional_year": { "default": false, "description": "Australia: completed a Professional Year in Australia", "type": "boolean" }, "community_language": { "default": false, "description": "Australia: NAATI credentialled community language", "type": "boolean" }, "partner_status": { "description": "Australia: partner points category; derived from `spouse` when omitted (no spouse → single, +10)", "type": "string", "enum": [ "single_or_partner_australian", "partner_skilled", "partner_competent_english", "partner_not_skilled" ] }, "uk_salary_gbp": { "description": "UK: gross annual salary in GBP", "type": "number", "minimum": 0 }, "uk_going_rate_gbp": { "description": "UK: occupation going rate in GBP (Appendix Skilled Occupations); omit to skip the going-rate test", "type": "number", "minimum": 0 }, "uk_job_skill_level_met": { "default": false, "description": "UK: job is at RQF level 6+ (or otherwise at the required skill level)", "type": "boolean" }, "uk_english_met": { "default": false, "description": "UK: meets the English requirement (CEFR B2 since 2026-01-08)", "type": "boolean" }, "uk_phd_relevant": { "default": false, "description": "UK: PhD relevant to the job (salary option B)", "type": "boolean" }, "uk_phd_stem": { "default": false, "description": "UK: STEM PhD relevant to the job (salary option C)", "type": "boolean" }, "uk_immigration_salary_list": { "default": false, "description": "UK: occupation on the Immigration Salary List / Temporary Shortage List (salary option D)", "type": "boolean" }, "uk_new_entrant": { "default": false, "description": "UK: qualifies as a new entrant (salary option E)", "type": "boolean" } }, "required": [ "age", "education" ] }, "include_improvement_paths": { "default": true, "description": "Include point-delta improvement paths in the response", "type": "boolean" } }, "required": [ "country", "program", "profile" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "calculate_immigration_eligibility" ] } }, "/credentials/verify": { "post": { "summary": "Professional Credential Verification", "description": "Professional license verification with entity matching, confidence scoring, and explicit data-coverage and staleness flags. Serving a seed dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "credential_verification", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "verify_professional_license", "credential_verification_coverage" ] } }, "/fda/enforcement/search": { "post": { "summary": "FDA Enforcement & Warning Letters", "description": "Search FDA warning letters, pull a company's enforcement history, and classify violation subjects into standardized categories with regulatory citations. Serving a seed dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "fda_warning_letter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "description": "Free-text FDA subject line or violation description to classify (e.g. 'CGMP/Finished Pharmaceuticals/Adulterated')" } }, "required": [ "description" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "search_fda_enforcement", "get_fda_enforcement_history", "classify_fda_violations" ] } }, "/tos/check-compliance": { "post": { "summary": "SaaS Terms of Service Compliance", "description": "Checks pre-analyzed SaaS terms across dimensions (commercial use, ML training, scraping, redistribution) and a deterministic clause engine for pasted text. Serving a curated dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "saas_tos", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tos_text": { "type": "string", "minLength": 40, "maxLength": 500000, "description": "Raw Terms of Service text to analyze (paste the relevant sections or the full document)" }, "use_case": { "default": "all", "description": "Specific dimension to analyze, or 'all' for all 7 dimensions", "type": "string", "enum": [ "commercial_use", "ml_training", "scraping", "redistribution", "competitive_use", "data_portability", "api_resale", "all" ] } }, "required": [ "tos_text" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "check_tos_compliance", "analyze_tos_text" ] } }, "/supplier-diversity/certifications": { "post": { "summary": "Supplier Diversity Certification", "description": "Verifies supplier diversity certifications (MBE, WBE, WOSB, DBE, 8(a), VetCert) with entity matching and expiry/revocation monitoring. Serving a seed dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "supplier_diversity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "suppliers": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": "string", "minLength": 2 }, "ein": { "type": "string", "pattern": "^\\d{2}-?\\d{7}$", "description": "Optional: employer identification number, 12-3456789 format. An EIN match uniquely identifies the entity." } }, "required": [ "company_name" ] }, "description": "Suppliers to check (the spec's monitored-supplier list), max 500 per call" }, "as_of_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date (YYYY-MM-DD) used to derive certification status (active/expired) and days_until_expiration. Defaults to the current UTC date when omitted." }, "alert_windows_days": { "description": "Override the default 90/60/30-day expiration alert windows", "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 366 } } }, "required": [ "suppliers" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "verify_supplier_diversity_certification" ] } }, "/content-policy/check": { "post": { "summary": "Platform Content Policy Compliance", "description": "Checks content against platform policies (YouTube, TikTok, Meta, LinkedIn, X, Google Ads) — paid disclosure, AI labeling, prohibited claims — as versioned, cited, deterministic rules.", "tags": [ "Compliance & Data Suite" ], "operationId": "content_policy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Content text to check (caption, script, ad copy, bio, or article body)" }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "facebook", "linkedin", "x", "google_ads" ], "description": "Target platform whose policy rules are applied" }, "content_type": { "default": "post", "description": "Kind of content being checked (default: post). Structural rules (length/hashtag limits) are content-type aware", "type": "string", "enum": [ "post", "video_script", "ad_copy", "comment", "bio", "article" ] }, "use_case": { "default": "organic", "description": "Optional: informs disclosure requirement checks (sponsored/paid_promotion → paid disclosure; ai_generated → AI label)", "type": "string", "enum": [ "organic", "sponsored", "paid_promotion", "ai_generated" ] }, "policy_year": { "default": 2026, "description": "Policy dataset vintage year (2026 supported). The response reports the exact policy_version", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "content", "platform" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "check_platform_compliance" ] } }, "/flight/check-compensation": { "post": { "summary": "Flight Delay Compensation", "description": "Passenger compensation eligibility and amounts across EU261, UK261, US DOT denied-boarding, and the Montreal Convention, with the extraordinary-circumstances analysis.", "tags": [ "Compliance & Data Suite" ], "operationId": "flight_compensation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "departure_airport": { "description": "Departure airport IATA code, e.g. LHR (bundled dataset of ~130 major airports)", "type": "string", "pattern": "^[A-Za-z]{3}$" }, "arrival_airport": { "description": "Final-destination airport IATA code, e.g. JFK", "type": "string", "pattern": "^[A-Za-z]{3}$" }, "departure_country": { "description": "Override / fallback: ISO-2 country of the departure airport (required if the IATA code is not bundled)", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "arrival_country": { "description": "Override / fallback: ISO-2 country of the final-destination airport", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "distance_km": { "description": "Override / fallback: great-circle route distance in km (EU261 Art 7(4)). If omitted, computed from bundled airport coordinates.", "type": "number", "exclusiveMinimum": 0, "maximum": 20038 }, "operating_carrier_country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO-2 country where the OPERATING carrier is licensed (EU261 applies to the operating carrier — FM2)" }, "marketing_carrier_country": { "description": "ISO-2 country of the marketing carrier if different (codeshare — triggers a confidence reduction)", "type": "string", "pattern": "^[A-Za-z]{2}$" }, "disruption_type": { "type": "string", "enum": [ "delay", "cancellation", "denied_boarding" ], "description": "delay | cancellation | denied_boarding" }, "delay_minutes": { "description": "Arrival delay at the final destination in minutes (negative = arrived early). The legal standard is ARRIVAL delay (Sturgeon; Germanwings C-452/13: doors-open time). Takes precedence over the timestamp pair.", "type": "integer", "minimum": -1440, "maximum": 10080 }, "scheduled_arrival": { "description": "Scheduled arrival, ISO 8601 with timezone (alternative to delay_minutes)", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "actual_arrival": { "description": "Actual arrival, ISO 8601 with timezone (alternative to delay_minutes)", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "delay_reason": { "default": "unknown", "description": "Cause of the disruption, if known — drives the extraordinary-circumstances flag and confidence", "type": "string", "enum": [ "weather", "atc", "airport_operations", "security", "political_instability", "strike_third_party", "strike_airline_staff", "bird_strike", "mechanical", "crew", "airline_operations", "unknown" ] }, "cancellation": { "description": "Required when disruption_type = cancellation", "type": "object", "properties": { "notice_days_before_departure": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Days before scheduled departure the passenger was informed of the cancellation" }, "rerouting_offered": { "default": false, "description": "Whether the carrier offered re-routing", "type": "boolean" }, "rerouting_departs_earlier_minutes": { "description": "How much earlier than the original schedule the offered re-routing departs (0 = same time or later)", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rerouting_arrival_delay_minutes": { "description": "How much later than the original schedule the offered re-routing arrives at the final destination", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "notice_days_before_departure" ] }, "denied_boarding": { "description": "Required when disruption_type = denied_boarding", "type": "object", "properties": { "voluntary": { "type": "boolean", "description": "True if the passenger gave up the seat voluntarily (voluntary DB has no fixed compensation entitlement)" }, "one_way_fare_usd": { "description": "One-way fare (incl. surcharges) in USD — required to compute US DOT denied boarding compensation", "type": "number", "exclusiveMinimum": 0 }, "arrival_delay_minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Arrival delay at the final destination on the substitute transport vs. the original schedule" } }, "required": [ "voluntary", "arrival_delay_minutes" ] } }, "required": [ "operating_carrier_country", "disruption_type" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "check_flight_compensation" ] } }, "/patent/status": { "post": { "summary": "Patent Expiration & Maintenance", "description": "Patent term calculation (20-year, PTA/PTE, terminal disclaimers) and the 3.5/7.5/11.5-year maintenance-fee windows. Serving a seed dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "patent_expiration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "patent_type": { "default": "utility", "description": "US patent type. Utility patents owe maintenance fees; design and plant patents do not", "type": "string", "enum": [ "utility", "design", "plant" ] }, "filing_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Earliest effective non-provisional US filing date (provisional filings do not count toward term)" }, "grant_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Patent grant (issue) date" }, "pta_days": { "default": 0, "description": "Patent Term Adjustment days (35 U.S.C. §154(b)) from USPTO published data", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pte_days": { "default": 0, "description": "Patent Term Extension days (35 U.S.C. §156, regulatory review)", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "terminal_disclaimer_date": { "description": "If a terminal disclaimer was filed, the disclaimed expiration date", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "fees_paid": { "default": [], "description": "Maintenance fee stages already paid (caller-asserted; utility patents only)", "type": "array", "items": { "type": "string", "enum": [ "3_5_year", "7_5_year", "11_5_year" ] } }, "as_of_date": { "description": "Date to evaluate status as of (YYYY-MM-DD). Defaults to today's date on the server", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "filing_date", "grant_date" ] } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "get_patent_status", "calculate_patent_expiration" ] } }, "/pharma/generic-entry": { "post": { "summary": "Generic Drug Entry Date", "description": "Estimates the earliest generic entry date from Hatch-Waxman exclusivities (NCE, ODE, pediatric, 180-day first-filer) and patent status. Serving a seed dataset during beta.", "tags": [ "Compliance & Data Suite" ], "operationId": "generic_entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "drug_name": { "description": "Brand name (e.g. LIPITOR) or generic name (e.g. atorvastatin calcium)", "type": "string", "minLength": 1 }, "nda_number": { "description": "Optional FDA application number for exact match (e.g. NDA020702, BLA125057)", "type": "string", "minLength": 1 }, "include_patent_detail": { "default": false, "description": "Include the full patent, exclusivity, and Paragraph IV breakdown", "type": "boolean" }, "as_of_date": { "description": "Reference date for expired/active status. Defaults to the bundled dataset's data_as_of. Provided as an input (never a server clock) so results are reproducible.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } }, "responses": { "200": { "description": "Calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "description": "Calculation output (per-API shape)." }, "data_as_of": { "type": "string" }, "formula_version": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string", "enum": [ "beta", "verified" ] } }, "required": [ "result", "data_as_of", "formula_version", "tier" ] } } } }, "400": { "description": "Validation or unsupported-parameter error" }, "401": { "description": "Missing or invalid API key" } }, "x-tier": "beta", "x-mcp-tools": [ "get_generic_entry_date" ] } } } }