{
  "openapi": "3.1.0",
  "info": {
    "title": "Driplee Clinical Math & ICU Infusion API",
    "description": "High-precision mathematical calculation and clinical decision-support API for intensive care unit (ICU) intravenous infusion rates, drug bag concentrations, and 19+ validated clinical scoring systems. Fully self-describing and optimized for LLM function-calling and autonomous agents.",
    "version": "1.0.0",
    "x-api-version": "1.0.0",
    "x-deprecation-policy": "APIs are maintained with backwards compatibility. Deprecated endpoints will be supported for a minimum of 12 months following formal deprecation notification and will return Sunset and Deprecation HTTP headers per RFC 8594.",
    "contact": {
      "name": "Driplee Medical Engineering Support",
      "email": "dripleestudio@gmail.com",
      "url": "https://driplee.online/contact"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://driplee.online",
      "description": "Production CDN Edge Service"
    }
  ],
  "paths": {
    "/api/health.json": {
      "get": {
        "operationId": "getSystemHealth",
        "summary": "Check API and Calculation Engine Health",
        "description": "Returns operational status, uptime timestamp, and version identifier of the Driplee clinical mathematical service.",
        "responses": {
          "200": {
            "description": "Calculation engine is active and operational.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/drugs.json": {
      "get": {
        "operationId": "listSupportedDrugs",
        "summary": "List Standard ICU Drug Formularies",
        "description": "Retrieves the standard catalog of critical care drugs (vasopressors, inotropes, sedatives, analgesics, antiarrhythmics, fluids) including default dilution amounts, volumes, dose units, and safe clinical titration ranges.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional clinical category filter (e.g., 'Vasopressors & Inotropes', 'Sedatives & Analgesics')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured array of drug categories and standard ICU presets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DrugCatalogResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/calculators.json": {
      "get": {
        "operationId": "getClinicalCalculators",
        "summary": "List Clinical Scoring Engines & Input Schemas",
        "description": "Retrieves metadata, input parameter constraints, clinical explanations, literature citations, and formulas for all 19+ clinical scoring calculators (P/F Ratio, MAP, eCrCl, Anion Gap, RSBI, Parkland, etc.).",
        "responses": {
          "200": {
            "description": "List of clinical calculators with complete input schemas and references.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculatorCatalogResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/calculate/infusion-rate": {
      "post": {
        "operationId": "calculateInfusionRate",
        "summary": "Calculate Volumetric IV Infusion Rate (mL/hr)",
        "description": "Computes exact infusion pump volumetric delivery rate in mL/hr from prescribed dose, patient weight in kg, total drug amount in bag, and dilution volume in mL. Incorporates strict division-by-zero safeguards.",
        "requestBody": {
          "required": true,
          "description": "Infusion parameters including dose, patient weight, and bag compounding details.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InfusionRateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully calculated infusion pump rate and intermediate steps.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InfusionRateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters (e.g. zero volume or negative weight).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/calculate/concentration": {
      "post": {
        "operationId": "calculateConcentration",
        "summary": "Calculate Final Drug Concentration in IV Solution",
        "description": "Calculates final concentration in mg/mL and mcg/mL when a drug mass is diluted into a specific volume of diluent.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConcentrationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Computed concentration values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConcentrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid volume or amount.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/calculate/clinical-score": {
      "post": {
        "operationId": "calculateClinicalScore",
        "summary": "Calculate Clinical Score or Risk Index",
        "description": "Executes a validated clinical mathematical formula (P/F Ratio, MAP, Cockcroft-Gault eCrCl, Anion Gap, RSBI, DTF, Corrected Sodium, Corrected Calcium) based on input values.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClinicalScoreRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculated score with clinical interpretation and classification badge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClinicalScoreResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or out-of-range clinical inputs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "version"],
        "properties": {
          "status": {
            "type": "string",
            "example": "healthy"
          },
          "service": {
            "type": "string",
            "example": "Driplee Clinical Math API"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DrugCatalogResponse": {
        "type": "object",
        "required": ["categories"],
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DrugCategory"
            }
          }
        }
      },
      "DrugCategory": {
        "type": "object",
        "required": ["id", "name", "drugs"],
        "properties": {
          "id": {
            "type": "string",
            "example": "vasopressors-inotropes"
          },
          "name": {
            "type": "string",
            "example": "Vasopressors & Inotropes"
          },
          "drugs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DrugPreset"
            }
          }
        }
      },
      "DrugPreset": {
        "type": "object",
        "required": ["id", "name", "doseUnit", "defaultDrugAmount", "defaultDrugAmountUnit", "defaultVolume", "defaultDose"],
        "properties": {
          "id": {
            "type": "string",
            "example": "norepinephrine"
          },
          "name": {
            "type": "string",
            "example": "Norepinephrine (Levophed)"
          },
          "doseUnit": {
            "type": "string",
            "example": "mcg/kg/min"
          },
          "defaultDrugAmount": {
            "type": "number",
            "example": 4
          },
          "defaultDrugAmountUnit": {
            "type": "string",
            "example": "mg"
          },
          "defaultVolume": {
            "type": "number",
            "example": 50
          },
          "defaultDose": {
            "type": "number",
            "example": 0.05
          },
          "range": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "example": [0.01, 3.0]
          },
          "engine": {
            "type": "string",
            "enum": ["drug", "fluid"],
            "example": "drug"
          }
        }
      },
      "CalculatorCatalogResponse": {
        "type": "object",
        "required": ["calculators"],
        "properties": {
          "calculators": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CalculatorMetadata"
            }
          }
        }
      },
      "CalculatorMetadata": {
        "type": "object",
        "required": ["id", "name", "category", "purpose", "formula"],
        "properties": {
          "id": {
            "type": "string",
            "example": "pf_ratio"
          },
          "name": {
            "type": "string",
            "example": "P/F Ratio (PaO2 / FiO2)"
          },
          "category": {
            "type": "string",
            "example": "Respiratory & Weaning"
          },
          "purpose": {
            "type": "string",
            "example": "Assesses severity of hypoxemia and ARDS under Berlin definition."
          },
          "formula": {
            "type": "string",
            "example": "PaO2 / (FiO2 / 100)"
          }
        }
      },
      "InfusionRateRequest": {
        "type": "object",
        "required": ["dose", "doseUnit", "bagAmount", "bagAmountUnit", "bagVolumeMl"],
        "properties": {
          "dose": {
            "type": "number",
            "minimum": 0,
            "description": "Prescribed dose amount",
            "example": 0.05
          },
          "doseUnit": {
            "type": "string",
            "enum": ["mcg/kg/min", "mcg/min", "mcg/kg/hr", "mg/kg/hr", "mg/hr", "unit/min", "unit/hr", "mL/kg/hr", "mL/hr"],
            "example": "mcg/kg/min"
          },
          "patientWeightKg": {
            "type": "number",
            "minimum": 0.1,
            "description": "Patient weight in kilograms (required if doseUnit is weight-based)",
            "example": 70
          },
          "bagAmount": {
            "type": "number",
            "minimum": 0.001,
            "description": "Total mass or units of drug compounded in the bag",
            "example": 4
          },
          "bagAmountUnit": {
            "type": "string",
            "enum": ["mg", "mcg", "g", "unit"],
            "example": "mg"
          },
          "bagVolumeMl": {
            "type": "number",
            "minimum": 0.1,
            "description": "Total volume of diluent solution in mL",
            "example": 50
          }
        }
      },
      "InfusionRateResponse": {
        "type": "object",
        "required": ["rateMlHr", "concentrationMgMl", "concentrationUnit"],
        "properties": {
          "rateMlHr": {
            "type": "number",
            "description": "Infusion rate in mL/hr rounded to appropriate clinical precision",
            "example": 2.63
          },
          "concentrationMgMl": {
            "type": "number",
            "description": "Final bag concentration in mg/mL",
            "example": 0.08
          },
          "concentrationMcgMl": {
            "type": "number",
            "description": "Final bag concentration in mcg/mL",
            "example": 80.0
          },
          "concentrationUnit": {
            "type": "string",
            "example": "mg/mL"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Drug concentration: 4 mg / 50 mL = 0.08 mg/mL (80 mcg/mL)",
              "Required delivery: 0.05 mcg/kg/min * 70 kg * 60 min = 210 mcg/hr (0.21 mg/hr)",
              "Infusion rate: 210 mcg/hr / 80 mcg/mL = 2.63 mL/hr"
            ]
          }
        }
      },
      "ConcentrationRequest": {
        "type": "object",
        "required": ["drugAmount", "amountUnit", "volumeMl"],
        "properties": {
          "drugAmount": {
            "type": "number",
            "minimum": 0.0001,
            "example": 250
          },
          "amountUnit": {
            "type": "string",
            "enum": ["mg", "mcg", "g", "unit"],
            "example": "mg"
          },
          "volumeMl": {
            "type": "number",
            "minimum": 0.1,
            "example": 250
          }
        }
      },
      "ConcentrationResponse": {
        "type": "object",
        "required": ["concentrationMgMl", "concentrationMcgMl"],
        "properties": {
          "concentrationMgMl": {
            "type": "number",
            "example": 1.0
          },
          "concentrationMcgMl": {
            "type": "number",
            "example": 1000.0
          },
          "summary": {
            "type": "string",
            "example": "1.0 mg/mL (1000 mcg/mL)"
          }
        }
      },
      "ClinicalScoreRequest": {
        "type": "object",
        "required": ["calculatorId", "values"],
        "properties": {
          "calculatorId": {
            "type": "string",
            "enum": [
              "pf_ratio",
              "map",
              "creatinine_clearance",
              "anion_gap",
              "rsbi_calculator",
              "corrected_sodium",
              "corrected_calcium",
              "osmolarity",
              "maintenance_fluid",
              "bmi",
              "bsa_mosteller"
            ],
            "example": "pf_ratio"
          },
          "values": {
            "type": "object",
            "description": "Key-value input parameters for calculator",
            "example": {
              "pao2": 85,
              "fio2": 50
            }
          }
        }
      },
      "ClinicalScoreResponse": {
        "type": "object",
        "required": ["value", "unit", "badge", "interpretation"],
        "properties": {
          "value": {
            "type": "string",
            "example": "170.0"
          },
          "unit": {
            "type": "string",
            "example": "mmHg"
          },
          "badge": {
            "type": "string",
            "example": "Moderate ARDS"
          },
          "interpretation": {
            "type": "string",
            "example": "Moderate ARDS (100 < P/F ≤ 200)"
          },
          "summary": {
            "type": "string",
            "example": "P/F Ratio: 170.0 mmHg (Moderate ARDS)"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "resolution"],
            "properties": {
              "code": {
                "type": "string",
                "example": "INVALID_PARAMETER"
              },
              "message": {
                "type": "string",
                "example": "Volume must be greater than 0 mL to prevent division by zero."
              },
              "resolution": {
                "type": "string",
                "example": "Ensure bagVolumeMl is a positive number (e.g. 50, 100, 250 mL)."
              }
            }
          }
        }
      }
    }
  }
}