openapi: 3.0.3
info:
  title: Medicare API
  description: Database-backed API for Medicare plans, providers, and pharmacies. 5,804 plans, 50,000 providers, 9,891 pharmacies.
  version: 3.0.0
servers:
  - url: https://medicare.purlpal-api.com/medicare
paths:
  /states.json:
    get:
      summary: List all states with plan counts
  /state/{state}/info.json:
    get:
      summary: Get state information
  /state/{state}/plans.json:
    get:
      summary: Get all plans in state
  /zip/{zipcode}.json:
    get:
      summary: Get plans by ZIP code
  /zip/{zipcode}_{category}.json:
    get:
      summary: Get plans by category (MAPD, MA, or PD)
  /plan/{planId}.json:
    get:
      summary: Get individual plan details
  /providers:
    get:
      summary: Search providers by ZIP code
      parameters:
        - name: zip
          in: query
          required: true
        - name: search
          in: query
          required: false
        - name: limit
          in: query
          required: false
  /pharmacies:
    get:
      summary: Search pharmacies by ZIP code
      parameters:
        - name: zip
          in: query
          required: true
        - name: search
          in: query
          required: false
        - name: limit
          in: query
          required: false
  /drugs/normalize:
    get:
      summary: Resolve noisy drug-name text to canonical FDA NDC entries
      description: Fuzzy-match against the FDA NDC Directory. Used by the pill-bottle scan flow to turn OCR output into a canonical drug name + dose candidates.
      parameters:
        - name: text
          in: query
          required: true
          description: Raw text (OCR, voice, or manual) to normalize
        - name: limit
          in: query
          required: false
          description: Max distinct (active_ingredient, strength) groups to return (default 5)