{
  "openapi": "3.1.0",
  "info": {
    "title": "ClearCarePulse API",
    "description": "Healthcare price transparency and cost navigation API. AI-synthesized procedure price search, cash-pay alternatives, hospital quality scoring, out-of-pocket estimation, insurance negotiation scripts, dental cost comparison, cosmetic procedure pricing, and episode-of-care bundling. Powered by CMS price transparency data (2024 mandate), Medicare benchmarks, and real cash-pay market data. Covers US-based healthcare \u2014 direct-pay clinic, telemedicine, and insurance comparison affiliates included. Sesame Care, MDsave, GoodRx, Teladoc, and HealthMarkets affiliate links injected into relevant endpoints. All endpoints support any language via ?lang=. Pricing: $0.10\u2013$0.20 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://clearcarepulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://clearcarepulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "required": true,
        "description": "x402 payment signature. Send a GET request without this header to receive a 402 with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/care/search": {
      "get": {
        "summary": "Procedure price search",
        "description": "Find lowest-cost providers for a procedure by zip code. Maps plain English to CPT codes, benchmarks against Medicare, returns providers sorted low-to-high by cash price.",
        "operationId": "careSearch",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Procedure name in plain English \u2014 e.g., 'knee MRI', 'colonoscopy', 'hip replacement'"
          },
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Patient zip code for geographic search"
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "25"
            },
            "description": "Search radius in miles"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Response language (e.g., 'Spanish')"
          }
        ],
        "responses": {
          "200": {
            "description": "Procedure price comparison sorted low-to-high"
          },
          "402": {
            "description": "Payment required",
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Core procedure price search \u2014 cash-pay clinic + insurance comparison affiliates auto-appended; chain to /api/care/oop for full out-of-pocket estimate"
      }
    },
    "/api/care/hospital": {
      "get": {
        "summary": "Hospital price lookup",
        "description": "Retrieve a specific hospital's published prices for a procedure. Includes chargemaster, negotiated rates by payer, cash price, Medicare benchmark, and negotiation script.",
        "operationId": "careHospital",
        "parameters": [
          {
            "name": "hospital",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Hospital name \u2014 e.g., 'Cleveland Clinic', 'Stanford Medical Center'"
          },
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Procedure name"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hospital price data with negotiation script"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Hospital quality and price scoring \u2014 chain after /api/care/search to evaluate providers; Medicare star rating + CMS data"
      }
    },
    "/api/care/episode": {
      "get": {
        "summary": "Total episode cost breakdown",
        "description": "Break down the full episode cost: surgeon fee, anesthesia, facility fee, PT, DME, follow-up. Calculates out-of-pocket liability with insurance parameters.",
        "operationId": "careEpisode",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deductible",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Annual deductible in USD"
          },
          {
            "name": "deductible_met",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Deductible already met this year in USD"
          },
          {
            "name": "coinsurance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Patient coinsurance % (default: 20)"
          },
          {
            "name": "oop_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Annual out-of-pocket maximum in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Total episode cost with OOP calculation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.2,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Episode-of-care bundling \u2014 surgery + anesthesia + facility pricing; pairs with /api/care/negotiate for full negotiation dossier"
      }
    },
    "/api/care/oop": {
      "get": {
        "summary": "Out-of-pocket cost calculator",
        "description": "Calculate exact patient liability given deductible, coinsurance, OOP max, and HSA status. Step-by-step breakdown with payment strategies.",
        "operationId": "careOop",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "procedure_cost",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Known procedure cost in USD"
          },
          {
            "name": "plan_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Plan type (Bronze, Silver, Gold, Platinum, employer)"
          },
          {
            "name": "deductible",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deductible_met",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "coinsurance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oop_max",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oop_spent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "OOP already spent this year in USD"
          },
          {
            "name": "hsa",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Has HSA (true/false)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OOP calculation with payment strategies"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Out-of-pocket cost estimator \u2014 chain after /api/care/search; pairs with /api/care/negotiate for cost reduction strategies"
      }
    },
    "/api/care/alternatives": {
      "get": {
        "summary": "Lower-cost care site alternatives",
        "description": "Find clinically appropriate lower-cost settings: ASC vs hospital outpatient, freestanding imaging centers, urgent care, FQHCs, telemedicine.",
        "operationId": "careAlternatives",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "current_setting",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Where currently scheduled (default: hospital outpatient)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lower-cost care alternatives with savings estimates"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Cash-pay and direct-primary-care alternatives \u2014 Sesame Care + MDsave affiliates auto-appended; highest affiliate revenue endpoint"
      }
    },
    "/api/care/negotiate": {
      "get": {
        "summary": "Medical bill negotiation guide",
        "description": "Step-by-step negotiation scripts, Medicare benchmark targeting, charity care eligibility assessment, and billing advocate referrals.",
        "operationId": "careNegotiate",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bill_amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bill amount in USD"
          },
          {
            "name": "hospital",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "insured",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Annual income in USD (for charity care eligibility)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Negotiation guide with scripts and savings estimate"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Insurance negotiation scripts \u2014 run after /api/care/oop to build negotiation case; healthcare financing affiliate included"
      }
    },
    "/api/care/dental": {
      "get": {
        "summary": "Dental cost intelligence",
        "description": "CDT code mapping, FairHealth UCR benchmarks (50th/80th/90th percentile), dental insurance vs. discount plan comparison, lower-cost alternatives.",
        "operationId": "careDental",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Dental procedure \u2014 e.g., 'crown', 'root canal', 'implant', 'deep cleaning'"
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_insurance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dental cost breakdown with benchmark comparison"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Dental cost comparison \u2014 pairs with /api/care/search for oral surgery pricing; direct-pay dental affiliates included"
      }
    },
    "/api/care/cosmetic": {
      "get": {
        "summary": "Cosmetic procedure cost intelligence",
        "description": "ASPS surgeon fee benchmarks, total episode cost breakdown (surgeon + anesthesia + facility), geographic adjustment, non-surgical alternatives, financing options.",
        "operationId": "careCosmetic",
        "parameters": [
          {
            "name": "procedure",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Cosmetic procedure \u2014 e.g., 'rhinoplasty', 'breast augmentation', 'botox', 'liposuction'"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "City or region for geographic adjustment"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cosmetic procedure cost breakdown with financing options"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Cosmetic procedure pricing \u2014 RealSelf data integration; chain with /api/care/alternatives for cash-pay options"
      }
    }
  }
}