{
  "openapi": "3.0.3",
  "info": {
    "title": "Appeal My Claim",
    "version": "1.1.0",
    "description": "Helps people in the US appeal a denied health insurance claim. Explains appeal rights and deadlines for private plans (job-based, Marketplace and individual, under the Affordable Care Act and ERISA), Original Medicare, Medicare Advantage, Medicare drug plans and Medicaid, points to each state's insurance department or Medicaid agency for free help (all 50 states, DC and Puerto Rico), decodes the denial codes on an Explanation of Benefits (like CO-50 or PR-204) in plain words, and drafts appeal letters by denial reason or code for the user to review and send. Every answer has a ready-to-read `say` line. Content is built in and checked against HealthCare.gov, CMS, Medicare.gov, the US Department of Labor and state sites. General information only, not legal or medical advice. It never files or sends anything. Read only, no account, nothing stored.",
    "contact": { "email": "hello@askmizan.com" }
  },
  "servers": [{ "url": "https://appealmyclaim.pages.dev" }],
  "paths": {
    "/v1/rights": {
      "get": {
        "operationId": "getAppealRights",
        "summary": "Appeal rights, steps and free help for a plan type and state",
        "description": "Use for \"what are my appeal rights in California?\", \"my insurer denied my claim, what can I do?\" or \"how do Medicare appeals work?\". Returns who decides, the steps (internal appeal, external review, Medicare levels or Medicaid fair hearing), deadlines, and where to get free help, including the state insurance department. If the plan type is not known, leave it out to get the rules for most private plans.",
        "parameters": [
          { "name": "state", "in": "query", "required": false, "description": "US state name or two-letter code, like California or CA. Puerto Rico works too.", "schema": { "type": "string", "example": "CA" } },
          { "name": "plan_type", "in": "query", "required": false, "description": "marketplace, employer, employer_insured, employer_self_funded, medicare, medicare_advantage, part_d or medicaid. Everyday words work too, like \"job\", \"Obamacare\" or \"Medi-Cal\". Default: most private plans.", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Rights and help" }, "400": { "description": "Unknown state or unsupported plan" } }
      }
    },
    "/v1/deadlines": {
      "get": {
        "operationId": "getAppealDeadlines",
        "summary": "How long someone has to appeal, and how fast the plan must decide",
        "description": "Use for \"how long do I have to appeal?\", \"when is my appeal due?\" or \"how fast does my insurer have to answer?\". With the date on the denial notice, gives an approximate file-by date. Remind the user to check the date on their own notice.",
        "parameters": [
          { "name": "plan_type", "in": "query", "required": false, "description": "Same values as /v1/rights. Default: most private plans.", "schema": { "type": "string" } },
          { "name": "denial_date", "in": "query", "required": false, "description": "Date on the denial notice, like 2026-09-01, 09/01/2026 or September 1, 2026.", "schema": { "type": "string", "maxLength": 20 } },
          { "name": "urgent", "in": "query", "required": false, "description": "yes if waiting could seriously harm the person's health.", "schema": { "type": "string", "enum": ["yes", "no"] } }
        ],
        "responses": { "200": { "description": "Deadlines" }, "400": { "description": "Bad date or unsupported plan" } }
      }
    },
    "/v1/denial-code": {
      "get": {
        "operationId": "explainDenialCode",
        "summary": "Explain the denial codes on an Explanation of Benefits",
        "description": "Use for \"my EOB says CO-50, what does that mean?\", \"what is denial code PR 204?\" or \"what does N130 mean?\". Returns each code in plain words, who usually fixes it (the provider's billing office, an appeal, or the user), whether the provider can bill the user for it (from the group code CO, PR, OA or PI), and a letter link when an appeal fits. Offer the letter after reading out say.",
        "parameters": [
          { "name": "code", "in": "query", "required": true, "description": "One to four codes from the notice, like CO-50, PR 204, 197 or N130.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "plan_type", "in": "query", "required": false, "description": "Same values as /v1/rights. Carried into the letter link.", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Codes explained, can_bill_you, letter and say" }, "400": { "description": "No code given" }, "404": { "description": "Code not known" } }
      }
    },
    "/v1/letter": {
      "get": {
        "operationId": "draftAppealLetter",
        "summary": "Draft an appeal letter for the user to review and send",
        "description": "Use for \"my insurer denied my MRI as not medically necessary, help me appeal\" or \"write an appeal letter for an out-of-network denial\". Returns a letter as plain text with [brackets] for anything not given, a checklist of what to attach (denial notice, doctor's letter of medical necessity, records), and tips. It never sends or files anything: read out the say line and offer the letter for the user to review and send.",
        "parameters": [
          { "name": "reason", "in": "query", "required": false, "description": "Why the claim was denied: medical_necessity, emergency (said it wasn't an emergency), experimental, out_of_network, prior_auth, coding or generic. Plain words work too. Required unless denial_code is given.", "schema": { "type": "string", "enum": ["medical_necessity", "emergency", "experimental", "out_of_network", "prior_auth", "coding", "generic"] } },
          { "name": "denial_code", "in": "query", "required": false, "description": "The reason code on the notice, like CO-50 or PR-197. Picks the reason when reason is left out, and is quoted in the letter.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "plan_type", "in": "query", "required": false, "description": "Same values as /v1/rights. Changes the wording for Medicare.", "schema": { "type": "string" } },
          { "name": "name", "in": "query", "required": false, "description": "Member's name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "plan", "in": "query", "required": false, "description": "Insurer or plan name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "member_id", "in": "query", "required": false, "description": "Member ID or Medicare number.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "claim", "in": "query", "required": false, "description": "Claim or reference number.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "service", "in": "query", "required": false, "description": "The care that was denied, like \"MRI of the right knee\".", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "date", "in": "query", "required": false, "description": "Date of service.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "denial_date", "in": "query", "required": false, "description": "Date on the denial notice.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "doctor", "in": "query", "required": false, "description": "Treating doctor's name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "provider", "in": "query", "required": false, "description": "Hospital, clinic or provider name.", "schema": { "type": "string", "maxLength": 80 } },
          { "name": "details", "in": "query", "required": false, "description": "A sentence or two in the user's words on why the care should be covered.", "schema": { "type": "string", "maxLength": 300 } },
          { "name": "urgent", "in": "query", "required": false, "description": "yes to ask for an expedited review.", "schema": { "type": "string", "enum": ["yes", "no"] } }
        ],
        "responses": { "200": { "description": "Letter draft" }, "400": { "description": "Missing or unknown reason, or a code that is not a denial" } }
      }
    },
    "/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" } } }
    }
  }
}