Calculator Endpoints — API Reference

Complete reference for all calculator REST API endpoints: request parameters, response format, and examples for each coil type.

1. Common Request Structure

All calculator endpoints accept a POST request with a JSON body. The body is structured into sections:

air: Air-side conditions (temperature, humidity, flow)
fluid / refrigerant: Fluid/refrigerant-side conditions
geometry: Coil physical dimensions and construction
options: Solver options (mode, maldistribution factor, etc.)

2. Chilled Water Coil

POST /api/v1/calculate/chilled-water

{ "air": { "T_db": 27, "T_wb": 19, "airFlow_m3h": 10000, "altitude_m": 0 }, "fluid": { "type": "water", "T_in": 7, "T_out": 12, "flowRate_kgh": 8600 }, "geometry": { "tubeOD_mm": 9.52, "tubeThk_mm": 0.35, "finPitch_fpi": 12, "finThk_mm": 0.1, "Pt_mm": 25.4, "Pl_mm": 22, "rows": 4, "tubesPerRow": 24, "circuits": 8, "finLength_mm": 1200 } }

Response includes total capacity (kW), sensible/latent split, SHR, leaving air conditions, air-side and fluid-side pressure drops, and UA value.

3. Hot Water Coil

POST /api/v1/calculate/hot-water

Same structure as chilled water, but with hot water temperatures (typically T_in: 60–90°C, T_out: 40–70°C). The air-side calculation is sensible-only (no dehumidification).

4. Steam Coil

POST /api/v1/calculate/steam-coil

{ "air": { "T_db": 15, "airFlow_m3h": 5000, "altitude_m": 0 }, "steam": { "pressure_kPa": 100, "quality": 1.0 }, "geometry": { ... } }

The steam section replaces the fluid section. Response includes heating capacity, condensate rate (kg/h), and leaving air temperature.

5. Dry Cooler

POST /api/v1/calculate/dry-cooler

Similar to hot water but for heat rejection. The fluid section supports glycol mixtures:

"fluid": { "type": "ethylene_glycol", "concentration": 30, "T_in": 40, "T_out": 35, "flowRate_kgh": 15000 }

6. DX Evaporator

POST /api/v1/calculate/dx-evaporator

POST /api/v1/calculate/dx-evaporator/balanced

{ "air": { "T_db": 27, "T_wb": 19, "airFlow_m3h": 8000, "altitude_m": 0 }, "refrigerant": { "type": "R410A", "T_evap": 7, "superheat_K": 8, "inletQuality": 0.22, "massFlow_kgh": 500 }, "geometry": { ... } }

The /balanced endpoint automatically finds the mass flow rate that closes the energy balance (Q_air = Q_ref). The standard endpoint uses the provided mass flow rate.

7. DX Condenser

POST /api/v1/calculate/dx-condenser

POST /api/v1/calculate/dx-condenser/balanced

"refrigerant": { "type": "R410A", "T_cond": 45, "subcooling_K": 5, "dischargeSH_K": 40, "massFlow_kgh": 600 }

Response includes zone breakdown (desuperheating, condensation, subcooling capacities), total heat rejection, and condenser status.

8. Refrigerants List

GET /api/v1/refrigerants

Returns the list of supported refrigerants with properties (GWP, ODP, safety class, critical temperature, critical pressure). No request body needed.

All calculation endpoints require the calc:read permission. The refrigerants endpoint is also available with calc:read.

9. Common Response Fields

Field	Type	Description
totalCapacity_kW	number	Total heat transfer capacity
sensibleCapacity_kW	number	Sensible capacity (cooling coils only)
latentCapacity_kW	number	Latent capacity (cooling coils only)
airPressureDrop_Pa	number	Air-side pressure drop
fluidPressureDrop_kPa	number	Fluid/refrigerant-side pressure drop
leavingAir	object	Leaving air conditions (T_db, T_wb, RH)
coilCode	string	Generated coil identification code