{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan High-Cost Medical Expense Check API",
    "version": "1.0.0",
    "description": "Big hospital bill in Japan? See your 高額療養費 monthly cap, what you really pay, the refund, the 4th-month rate, the new Aug–Jul yearly cap from 2026, how the August 2027 change hits your income band and your 2-year claim deadline. English + 日本語.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp"
  },
  "servers": [
    {
      "url": "https://japan-medical-cost-cap.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanHighCostMedicalCheck",
        "summary": "Japan high-cost medical expense cap (高額療養費): your monthly cap, what you really pay, the refund, the 4th-month rate, the new Aug–Jul annual cap, the Aug 2027 change and the claim deadline.",
        "description": "Applies Japan's 高額療養費 rules as of 2026-11-04 (MHLW review: caps rose for treatment from 2026-08 with a new yearly cap; from 2027-08 the bands split into 12). Monthly cap = base + (10割 total − threshold) × 1% (flat for lower bands); 多数回該当 from the 4th benefit month in 12; yearly cap per Aug–Jul on what you paid after monthly refunds (¥1.68M / ¥1.11M / ¥530k / ¥410k / ¥290k / 70+ 低所得I ¥180k); 70+ outpatient caps (¥18,000 → ¥22,000 → ¥28,000 for 一般). Give income one way: band, standardMonthlyRemuneration (employee insurance 標準報酬月額), nhiIncome (NHI 旧ただし書き所得), taxableIncome (70+ 課税所得) or rough annualIncome; or nonTaxable=true. Returns verdict (under_cap | cap_applies | many_times_cap | annual_cap_reached), summary, band {id, label, source}, schedule, month {monthlyCap, formula, youPay, monthlyRefund, manyTimes}, caps, annualCap {period, amount}, from2027 {monthlyCap, youPay, changeJPY}, beforeAug2026, claim {deadline}, tracker {months[], years[{annualRefund}]} when months are given, steps, notCounted, sources, disclaimer. Insured care only: meals, private rooms, 先進医療 and uninsured care don't count.\n\nExample: https://japan-medical-cost-cap.vercel.app/api/check?month=2026-11&totalCost=1000000&standardMonthlyRemuneration=300000",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "description": "Treatment month YYYY-MM (default this month in JST). Picks the schedule: up to 2026-07, 2026-08…2027-07, 2027-08+.",
            "schema": {
              "type": "string",
              "description": "Treatment month YYYY-MM (default this month in JST). Picks the schedule: up to 2026-07, 2026-08…2027-07, 2027-08+."
            }
          },
          {
            "name": "totalCost",
            "in": "query",
            "required": false,
            "description": "10割 total medical cost on the bill (総医療費), yen. Accepts 100万.",
            "schema": {
              "type": "number",
              "description": "10割 total medical cost on the bill (総医療費), yen. Accepts 100万."
            }
          },
          {
            "name": "copay",
            "in": "query",
            "required": false,
            "description": "What you paid at the counter for insured care (窓口負担), yen. Give this or totalCost.",
            "schema": {
              "type": "number",
              "description": "What you paid at the counter for insured care (窓口負担), yen. Give this or totalCost."
            }
          },
          {
            "name": "ageGroup",
            "in": "query",
            "required": false,
            "description": "under70 or 70plus (70–74 and 75+ 後期高齢者). A number age also works.",
            "schema": {
              "type": "string",
              "description": "under70 or 70plus (70–74 and 75+ 後期高齢者). A number age also works.",
              "enum": [
                "under70",
                "70plus"
              ],
              "default": "under70"
            }
          },
          {
            "name": "band",
            "in": "query",
            "required": false,
            "description": "Income band directly (y370 = income about ¥3.7M–5.1M). Old letters ア/イ/ウ/エ/オ map to a middle band.",
            "schema": {
              "type": "string",
              "description": "Income band directly (y370 = income about ¥3.7M–5.1M). Old letters ア/イ/ウ/エ/オ map to a middle band.",
              "enum": [
                "y1650",
                "y1410",
                "y1160",
                "y1040",
                "y950",
                "y770",
                "y650",
                "y510",
                "y370",
                "y260",
                "y200",
                "y0",
                "nontaxable",
                "nontaxable_low"
              ]
            }
          },
          {
            "name": "standardMonthlyRemuneration",
            "in": "query",
            "required": false,
            "description": "Employee insurance 標準報酬月額 in yen (e.g. 300000).",
            "schema": {
              "type": "number",
              "description": "Employee insurance 標準報酬月額 in yen (e.g. 300000)."
            }
          },
          {
            "name": "nhiIncome",
            "in": "query",
            "required": false,
            "description": "National Health Insurance 旧ただし書き所得 (household total) in yen.",
            "schema": {
              "type": "number",
              "description": "National Health Insurance 旧ただし書き所得 (household total) in yen."
            }
          },
          {
            "name": "taxableIncome",
            "in": "query",
            "required": false,
            "description": "70+: resident-tax 課税所得 in yen.",
            "schema": {
              "type": "number",
              "description": "70+: resident-tax 課税所得 in yen."
            }
          },
          {
            "name": "annualIncome",
            "in": "query",
            "required": false,
            "description": "Rough annual income (年収) in yen, if nothing better is known.",
            "schema": {
              "type": "number",
              "description": "Rough annual income (年収) in yen, if nothing better is known."
            }
          },
          {
            "name": "nonTaxable",
            "in": "query",
            "required": false,
            "description": "Resident-tax exempt household (住民税非課税).",
            "schema": {
              "type": "boolean",
              "description": "Resident-tax exempt household (住民税非課税).",
              "default": false
            }
          },
          {
            "name": "burdenRate",
            "in": "query",
            "required": false,
            "description": "Copay rate 0.1 / 0.2 / 0.3 (default 0.3 under 70; 70+ 0.3 for high bands else 0.2).",
            "schema": {
              "type": "number",
              "description": "Copay rate 0.1 / 0.2 / 0.3 (default 0.3 under 70; 70+ 0.3 for high bands else 0.2)."
            }
          },
          {
            "name": "setting",
            "in": "query",
            "required": false,
            "description": "inpatient (or any household total) / outpatient (70+ outpatient-only cap per person).",
            "schema": {
              "type": "string",
              "description": "inpatient (or any household total) / outpatient (70+ outpatient-only cap per person).",
              "enum": [
                "inpatient",
                "outpatient"
              ],
              "default": "inpatient"
            }
          },
          {
            "name": "manyTimes",
            "in": "query",
            "required": false,
            "description": "Already had a benefit in 3+ of the last 12 months (多数回該当).",
            "schema": {
              "type": "boolean",
              "description": "Already had a benefit in 3+ of the last 12 months (多数回該当).",
              "default": false
            }
          },
          {
            "name": "priorHitMonths",
            "in": "query",
            "required": false,
            "description": "Benefit months in the 12 months before (3+ = 多数回).",
            "schema": {
              "type": "integer",
              "description": "Benefit months in the 12 months before (3+ = 多数回).",
              "minimum": 0,
              "maximum": 11
            }
          },
          {
            "name": "months",
            "in": "query",
            "required": false,
            "description": "Optional yearly tracker: \"2026-08:300000,2026-09:300000\" (month:10割 total[:outpatient]; prefix copay for copay amounts) or POST array [{month,totalCost|copay,setting}]. Auto-applies 多数回 and the Aug–Jul annual cap.",
            "schema": {
              "type": "string",
              "description": "Optional yearly tracker: \"2026-08:300000,2026-09:300000\" (month:10割 total[:outpatient]; prefix copay for copay amounts) or POST array [{month,totalCost|copay,setting}]. Auto-applies 多数回 and the Aug–Jul annual cap."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "japanHighCostMedicalCheckPost",
        "summary": "Japan high-cost medical expense cap (高額療養費): your monthly cap, what you really pay, the refund, the 4th-month rate, the new Aug–Jul annual cap, the Aug 2027 change and the claim deadline. (JSON body)",
        "description": "Applies Japan's 高額療養費 rules as of 2026-11-04 (MHLW review: caps rose for treatment from 2026-08 with a new yearly cap; from 2027-08 the bands split into 12). Monthly cap = base + (10割 total − threshold) × 1% (flat for lower bands); 多数回該当 from the 4th benefit month in 12; yearly cap per Aug–Jul on what you paid after monthly refunds (¥1.68M / ¥1.11M / ¥530k / ¥410k / ¥290k / 70+ 低所得I ¥180k); 70+ outpatient caps (¥18,000 → ¥22,000 → ¥28,000 for 一般). Give income one way: band, standardMonthlyRemuneration (employee insurance 標準報酬月額), nhiIncome (NHI 旧ただし書き所得), taxableIncome (70+ 課税所得) or rough annualIncome; or nonTaxable=true. Returns verdict (under_cap | cap_applies | many_times_cap | annual_cap_reached), summary, band {id, label, source}, schedule, month {monthlyCap, formula, youPay, monthlyRefund, manyTimes}, caps, annualCap {period, amount}, from2027 {monthlyCap, youPay, changeJPY}, beforeAug2026, claim {deadline}, tracker {months[], years[{annualRefund}]} when months are given, steps, notCounted, sources, disclaimer. Insured care only: meals, private rooms, 先進医療 and uninsured care don't count.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "month": {
                    "type": "string",
                    "description": "Treatment month YYYY-MM (default this month in JST). Picks the schedule: up to 2026-07, 2026-08…2027-07, 2027-08+."
                  },
                  "totalCost": {
                    "type": "number",
                    "description": "10割 total medical cost on the bill (総医療費), yen. Accepts 100万."
                  },
                  "copay": {
                    "type": "number",
                    "description": "What you paid at the counter for insured care (窓口負担), yen. Give this or totalCost."
                  },
                  "ageGroup": {
                    "type": "string",
                    "description": "under70 or 70plus (70–74 and 75+ 後期高齢者). A number age also works.",
                    "enum": [
                      "under70",
                      "70plus"
                    ],
                    "default": "under70"
                  },
                  "band": {
                    "type": "string",
                    "description": "Income band directly (y370 = income about ¥3.7M–5.1M). Old letters ア/イ/ウ/エ/オ map to a middle band.",
                    "enum": [
                      "y1650",
                      "y1410",
                      "y1160",
                      "y1040",
                      "y950",
                      "y770",
                      "y650",
                      "y510",
                      "y370",
                      "y260",
                      "y200",
                      "y0",
                      "nontaxable",
                      "nontaxable_low"
                    ]
                  },
                  "standardMonthlyRemuneration": {
                    "type": "number",
                    "description": "Employee insurance 標準報酬月額 in yen (e.g. 300000)."
                  },
                  "nhiIncome": {
                    "type": "number",
                    "description": "National Health Insurance 旧ただし書き所得 (household total) in yen."
                  },
                  "taxableIncome": {
                    "type": "number",
                    "description": "70+: resident-tax 課税所得 in yen."
                  },
                  "annualIncome": {
                    "type": "number",
                    "description": "Rough annual income (年収) in yen, if nothing better is known."
                  },
                  "nonTaxable": {
                    "type": "boolean",
                    "description": "Resident-tax exempt household (住民税非課税).",
                    "default": false
                  },
                  "burdenRate": {
                    "type": "number",
                    "description": "Copay rate 0.1 / 0.2 / 0.3 (default 0.3 under 70; 70+ 0.3 for high bands else 0.2)."
                  },
                  "setting": {
                    "type": "string",
                    "description": "inpatient (or any household total) / outpatient (70+ outpatient-only cap per person).",
                    "enum": [
                      "inpatient",
                      "outpatient"
                    ],
                    "default": "inpatient"
                  },
                  "manyTimes": {
                    "type": "boolean",
                    "description": "Already had a benefit in 3+ of the last 12 months (多数回該当).",
                    "default": false
                  },
                  "priorHitMonths": {
                    "type": "integer",
                    "description": "Benefit months in the 12 months before (3+ = 多数回).",
                    "minimum": 0,
                    "maximum": 11
                  },
                  "months": {
                    "type": "string",
                    "description": "Optional yearly tracker: \"2026-08:300000,2026-09:300000\" (month:10割 total[:outpatient]; prefix copay for copay amounts) or POST array [{month,totalCost|copay,setting}]. Auto-applies 多数回 and the Aug–Jul annual cap."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    },
    "/api/rules": {
      "get": {
        "operationId": "japanHighCostMedicalRules",
        "summary": "Japan 高額療養費 rules: cap formula and full cap tables for all three schedules (to 2026-07, 2026-08…2027-07, 2027-08+), 14 income bands with income ranges, 多数回 rate, Aug–Jul annual caps, 70+ outpatient caps, claim deadline, sources",
        "description": "Returns the rules the checker applies, with the legal periods, sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}