{
  "openapi": "3.0.3",
  "info": {
    "title": "Med Bill Check",
    "version": "1.1.0",
    "description": "Checks a US medical bill against Medicare's published rates and drafts letters the user can send. Look up a service by billing code (CPT or HCPCS, like 99213) or in plain words (like knee MRI), nationally or for a state, and compare a charged amount with Medicare's typical allowed amount and the amount providers typically bill. Drafts letters to request an itemized bill, ask for a charge to be reviewed, ask for a prompt-pay or self-pay discount, or apply for hospital financial assistance, and explains No Surprises Act and Good Faith Estimate rights. Checks a whole itemized bill for questions worth asking (repeated codes, units above Medicare's daily limits, charges far above what providers bill, hospital clinic facility fees), and says whether a hospital is nonprofit, which means it must offer financial assistance. Every answer has a ready-to-read `say` line. Medicare rates are the 2026 fee schedule for the state or city, alongside what providers typically billed in 2024. They are a common benchmark, not a verdict on any bill. General information only, not medical, legal or financial advice. Letters are drafts: the user reviews and sends them. Read only, no account, nothing stored. Data: CMS Medicare Physician Fee Schedule 2026, Medicare Physician and Other Practitioners and Medicare Outpatient Hospitals by Geography and Service, NCCI Medically Unlikely Edits and Hospital General Information (cms.gov).",
    "contact": { "email": "hello@askmizan.com" }
  },
  "servers": [{ "url": "https://medbillcheck.pages.dev" }],
  "paths": {
    "/v1/price": {
      "get": {
        "operationId": "checkPrice",
        "summary": "Compare a charge with Medicare's rate for one service",
        "description": "Use when someone asks whether a charge is high or what Medicare pays, for example \"I was charged $450 for a 99213 office visit in Texas, is that too high?\" or \"what does Medicare pay for an MRI of the knee?\". Pass the billing code if they have it, otherwise the service in plain words as q. Returns Medicare's 2026 rate for the state (or the city's own pricing area when city is given) in medicare_2026, the amount providers typically billed in 2024, and how many times the Medicare rate the charge is. Present it as a common benchmark, never as proof the bill is wrong. Dental work has no Medicare rate and returns 404 with a pointer to a free dental cost source.",
        "parameters": [
          { "name": "code", "in": "query", "required": false, "description": "Five-character CPT or HCPCS code from the bill, like 99213, 73721 or G0121.", "schema": { "type": "string", "example": "99213" } },
          { "name": "q", "in": "query", "required": false, "description": "The service in plain words, used when there is no code, like \"knee MRI\" or \"ER visit\".", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "state", "in": "query", "required": false, "description": "US state name or two-letter code, like Texas or TX.", "schema": { "type": "string", "example": "TX" } },
          { "name": "charged", "in": "query", "required": false, "description": "The amount on the bill in US dollars, like 450.", "schema": { "type": "number", "minimum": 1, "maximum": 5000000 } },
          { "name": "setting", "in": "query", "required": false, "description": "office (clinic, office, imaging center) or facility (hospital or surgery center). Leave out to use the usual setting.", "schema": { "type": "string", "enum": ["office", "facility"] } },
          { "name": "city", "in": "query", "required": false, "description": "City, for states where Medicare pays big cities differently, like Houston, Chicago, Miami or Los Angeles. Other places use the rest-of-state rate.", "schema": { "type": "string", "maxLength": 60 } }
        ],
        "responses": { "200": { "description": "Benchmark and comparison" }, "400": { "description": "Bad or missing input" }, "404": { "description": "Code not found" }, "503": { "description": "CMS data not answering" } }
      }
    },
    "/v1/search": {
      "get": {
        "operationId": "searchServices",
        "summary": "Find billing codes and Medicare rates by plain words",
        "description": "Use when someone describes a service but has no code, or asks what a code means, for example \"what's the code for a colonoscopy?\", \"how much does Medicare pay for a chest x-ray in Ohio?\" or \"what is code 99214?\". Returns up to eight matching codes with Medicare's typical allowed and billed amounts.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Plain words or a code, like \"hernia repair\" or 99214.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "state", "in": "query", "required": false, "description": "US state name or two-letter code.", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Matching services" }, "400": { "description": "Missing query" }, "404": { "description": "Nothing found" }, "503": { "description": "CMS data not answering" } }
      }
    },
    "/v1/check": {
      "get": {
        "operationId": "checkWholeBill",
        "summary": "Check several lines of an itemized bill at once",
        "description": "Use when someone reads out or pastes several lines from an itemized bill, for example \"my ER bill has 99284 for $2,500, 85025 twice for $120 and 36415 three times, does anything look off?\". Pass the lines as code, optional x and units, then the amount. Returns each line against Medicare's rate, totals, and questions_to_ask: repeated codes, units above Medicare's automated daily limit, the highest visit levels, hospital clinic facility fees and charges far above what providers typically bill. Present these as questions for the billing office, never as proof of an error.",
        "parameters": [
          { "name": "lines", "in": "query", "required": true, "description": "Up to 15 bill lines separated by commas: code, then x and units if more than one, then the amount. Example: 99284:2500, 85025x2:120, 36415:45.", "schema": { "type": "string", "maxLength": 600 } },
          { "name": "state", "in": "query", "required": false, "description": "US state name or two-letter code.", "schema": { "type": "string" } },
          { "name": "city", "in": "query", "required": false, "description": "City, for big cities with their own Medicare rates.", "schema": { "type": "string", "maxLength": 60 } },
          { "name": "setting", "in": "query", "required": false, "description": "office or facility. Leave out if not known.", "schema": { "type": "string", "enum": ["office", "facility"] } }
        ],
        "responses": { "200": { "description": "Lines, totals, questions_to_ask and say" }, "400": { "description": "Lines missing or unreadable" }, "503": { "description": "CMS data not answering" } }
      }
    },
    "/v1/hospital": {
      "get": {
        "operationId": "lookUpHospital",
        "summary": "Whether a hospital is nonprofit, for financial assistance",
        "description": "Use for \"is St. Luke's in Boise a nonprofit?\" or \"does this hospital have to offer charity care?\". Returns how Medicare lists the hospital's ownership (nonprofit, government, for-profit), its city and main phone number, and what that means for financial assistance. Nonprofit hospitals must have a financial assistance policy. Offer the assistance letter next.",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "description": "Hospital name as on the bill, like St. Luke's Regional Medical Center.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "state", "in": "query", "required": false, "description": "US state name or two-letter code. Recommended, since many hospitals share names.", "schema": { "type": "string" } },
          { "name": "city", "in": "query", "required": false, "description": "City, to pick between hospitals with the same name.", "schema": { "type": "string", "maxLength": 60 } }
        ],
        "responses": { "200": { "description": "Matching hospitals with ownership and say" }, "400": { "description": "Name missing" }, "404": { "description": "No matching hospital" }, "503": { "description": "CMS data not answering" } }
      }
    },
    "/v1/letter": {
      "get": {
        "operationId": "draftBillLetter",
        "summary": "Draft a letter to a billing office for the user to send",
        "description": "Use for \"help me dispute this bill\", \"write a letter asking for an itemized bill\", \"can I ask for a discount?\" or \"how do I apply for charity care?\". Returns a letter as plain text with [brackets] for anything not given, tips, and the user's No Surprises Act and Good Faith Estimate rights with official CMS links. It never sends anything: read out the say line and offer the letter for the user to review and send.",
        "parameters": [
          { "name": "type", "in": "query", "required": true, "description": "itemized (ask for an itemized bill), dispute (ask for a charge to be reviewed), discount (prompt-pay or self-pay discount), or assistance (financial assistance or charity care).", "schema": { "type": "string", "enum": ["itemized", "dispute", "discount", "assistance"] } },
          { "name": "name", "in": "query", "required": false, "description": "Patient or account holder name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "provider", "in": "query", "required": false, "description": "Hospital, clinic or provider name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "account", "in": "query", "required": false, "description": "Account or invoice number on the bill.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "date", "in": "query", "required": false, "description": "Date of service.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "service", "in": "query", "required": false, "description": "The service in plain words.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "code", "in": "query", "required": false, "description": "Billing code of the charge. With amount, a dispute letter adds Medicare's benchmark.", "schema": { "type": "string" } },
          { "name": "amount", "in": "query", "required": false, "description": "Amount charged or balance due, in US dollars.", "schema": { "type": "number", "minimum": 1, "maximum": 5000000 } },
          { "name": "state", "in": "query", "required": false, "description": "US state, used for the benchmark in a dispute letter.", "schema": { "type": "string" } },
          { "name": "reason", "in": "query", "required": false, "description": "A sentence on what the user wants checked, for a dispute letter.", "schema": { "type": "string", "maxLength": 300 } },
          { "name": "insured", "in": "query", "required": false, "description": "no if paying without insurance (self-pay), for a discount letter.", "schema": { "type": "string", "enum": ["yes", "no"] } }
        ],
        "responses": { "200": { "description": "Letter draft" }, "400": { "description": "Bad or missing letter type" } }
      }
    },
    "/v1/health": {
      "get": { "operationId": "health", "summary": "Service status", "description": "Only for checking the service is up. Not needed to answer users.", "responses": { "200": { "description": "OK" } } }
    }
  }
}