{
 "openapi": "3.1.0",
 "info": {
  "title": "Fuel-Cell Digital Twin Lab API",
  "version": "1.0.0",
  "description": "PEM and SOFC twin models, stack sizing, aviation comparison and the evidence board. Every response carries a `status`: MODEL_OUTPUT_NOT_VALIDATED, SCREENING_ESTIMATE or FROZEN_OUTPUT. Live endpoints run the same code as `archee.api` (parity tested); others are precomputed at build time."
 },
 "servers": [
  {
   "url": "https://fuelcell.vassalenterprises.com"
  }
 ],
 "paths": {
  "/api/v1/pem/point": {
   "get": {
    "summary": "PEM cell operating point (live)",
    "parameters": [
     {
      "name": "j_A_cm2",
      "in": "query",
      "required": true,
      "description": "Current density, A/cm²",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "T_C",
      "in": "query",
      "required": false,
      "description": "Cell temperature, °C",
      "schema": {
       "type": "number",
       "default": 75
      }
     },
     {
      "name": "pressure_bar",
      "in": "query",
      "required": false,
      "description": "Absolute cathode pressure, bar",
      "schema": {
       "type": "number",
       "default": 2.51325
      }
     },
     {
      "name": "rh",
      "in": "query",
      "required": false,
      "description": "Inlet RH, 0-1",
      "schema": {
       "type": "number",
       "default": 0.6
      }
     },
     {
      "name": "stoich",
      "in": "query",
      "required": false,
      "description": "Cathode stoichiometry",
      "schema": {
       "type": "number",
       "default": 2.0
      }
     },
     {
      "name": "calibration",
      "in": "query",
      "required": false,
      "description": "lab (frozen anchor) or mirai (resistance refitted to public Toyota Mirai data; use T_C=80, pressure_bar=2.533)",
      "schema": {
       "type": "string",
       "default": "lab"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Operating point"
     },
     "422": {
      "description": "Outside the model domain"
     }
    }
   }
  },
  "/api/v1/size": {
   "get": {
    "summary": "Screening stack sizing (live)",
    "parameters": [
     {
      "name": "power_kW",
      "in": "query",
      "required": true,
      "description": "Net electrical power, kW",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "cell_voltage_V",
      "in": "query",
      "required": true,
      "description": "Cell voltage, V",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "j_A_cm2",
      "in": "query",
      "required": true,
      "description": "Current density, A/cm²",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "chemistry",
      "in": "query",
      "required": false,
      "description": "pem or sofc",
      "schema": {
       "type": "string",
       "default": "pem"
      }
     },
     {
      "name": "cell_area_cm2",
      "in": "query",
      "required": false,
      "description": "Active area per cell, cm²",
      "schema": {
       "type": "number",
       "default": 280
      }
     },
     {
      "name": "specific_power_kW_kg",
      "in": "query",
      "required": false,
      "description": "kW/kg, one value or \"low,high\", for a mass estimate",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Sizing"
     },
     "422": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/v1/sofc/point": {
   "get": {
    "summary": "SOFC cell operating point (live)",
    "parameters": [
     {
      "name": "voltage_V",
      "in": "query",
      "required": true,
      "description": "Cell voltage, V",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "sofc_class",
      "in": "query",
      "required": false,
      "description": "ref (0.6 W/cm² at 0.8 V), high (1.0 W/cm² at 0.8 V) or rig (twin rig cell, interpolated)",
      "schema": {
       "type": "string",
       "default": "ref"
      }
     },
     {
      "name": "T_C",
      "in": "query",
      "required": false,
      "description": "Rig cell temperature: 700, 750 or 800",
      "schema": {
       "type": "number",
       "default": 800
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Operating point"
     },
     "422": {
      "description": "Outside the range"
     }
    }
   }
  },
  "/api/v1/system": {
   "get": {
    "summary": "Stacks, balance of plant, mass and kW/kg (live)",
    "parameters": [
     {
      "name": "net_kW",
      "in": "query",
      "required": true,
      "description": "Net power, kW",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "chemistry",
      "in": "query",
      "required": false,
      "description": "pem or sofc",
      "schema": {
       "type": "string",
       "default": "pem"
      }
     },
     {
      "name": "year",
      "in": "query",
      "required": false,
      "description": "2026, 2030, 2035 or 2050",
      "schema": {
       "type": "string",
       "default": "2030"
      }
     },
     {
      "name": "pem_calibration",
      "in": "query",
      "required": false,
      "description": "mirai or lab",
      "schema": {
       "type": "string",
       "default": "mirai"
      }
     },
     {
      "name": "sofc_class",
      "in": "query",
      "required": false,
      "description": "ref, high or rig",
      "schema": {
       "type": "string",
       "default": "ref"
      }
     },
     {
      "name": "mass_case",
      "in": "query",
      "required": false,
      "description": "baseline (today's hardware: PEM stack 2.0, system 1.4; SOFC stack 0.3 kW/kg) or targets (FlyZero; HYLENA 3 kW/kg)",
      "schema": {
       "type": "string",
       "default": "baseline"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "System estimate"
     },
     "422": {
      "description": "Invalid input"
     }
    }
   }
  },
  "/api/v1/models.json": {
   "get": {
    "summary": "API function registry",
    "description": "Signatures and one-line help for every archee.api function.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/pem/curve-{T}C.json": {
   "get": {
    "summary": "PEM polarization curve, lab anchor",
    "description": "T = 65, 75 or 85.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/pem/curve-mirai-80C.json": {
   "get": {
    "summary": "PEM polarization curve, Mirai-class calibration",
    "description": "80 °C, 2.53 bar.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/pem/calibration-mirai.json": {
   "get": {
    "summary": "Mirai-class calibration record",
    "description": "Fit point, sensitivity, checks and limits.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/compare/aviation-lab.json": {
   "get": {
    "summary": "Aviation comparison with the lab-anchor PEM cell",
    "description": "Same as aviation.json, lab calibration.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/sofc/curve-{T}C.json": {
   "get": {
    "summary": "SOFC polarization curve",
    "description": "T = 700, 750 or 800. Precomputed: the SOFC model integrates an ODE.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/compare/aviation.json": {
   "get": {
    "summary": "PEM vs SOFC for the three H2FLY steps",
    "description": "Sizing and published context per step.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/evidence.json": {
   "get": {
    "summary": "Evidence board",
    "description": "Frozen outputs with source paths and SHA-256.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/plan.json": {
   "get": {
    "summary": "Next PEM test batch",
    "description": "Proposed, not executed.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  },
  "/api/v1/sofc/impedance-record-05.json": {
   "get": {
    "summary": "SOFC impedance record",
    "description": "Frozen record 05 for Nyquist Bench.",
    "responses": {
     "200": {
      "description": "JSON"
     }
    }
   }
  }
 }
}