{
 "openapi": "3.1.0",
 "info": {
  "title": "xmoo Cable Sizing API",
  "version": "0.1.0",
  "summary": "Size low-voltage cables to IEC 60364 / DIN VDE: current-carrying capacity, protective device, voltage drop, automatic disconnection and short-circuit withstand – with every step shown.",
  "description": "Current-carrying capacities and correction factors come from DIN VDE 0298-4:2023-06 (Tables 3–6, 17, 20–26, 29), whose values are those of HD 60364-5-52 / IEC 60364-5-52 Annex B; every answer names the table and column. Copper and aluminium, PVC 70 °C and cross-linked 90 °C insulation, installation methods A1 to G, up to 300 mm² (F and G up to 630 mm²). The calculation follows IEC 60364-4-43 (Ib ≤ In ≤ Iz, I2 ≤ 1.45 Iz), IEC 60364-5-52 (voltage drop, resistive part) and IEC 60364-4-41 with the minimum single-phase fault current per IEC 60909-0 (cmin = 0.9, conductor at its permissible short-circuit temperature). Nothing is stored. Planning aid without warranty: it replaces neither professional design nor verification to IEC 60364-6. Provider: Haag Automation (xmoo.app). Same engine as the free tool on https://xmoo.app/tools/kabelberechnung/. Texts are English by default; `lang=de` returns German.",
  "contact": {
   "name": "Haag Automation",
   "email": "julian@haag-automation.com",
   "url": "https://xmoo.app"
  },
  "license": {
   "name": "Proprietary"
  }
 },
 "servers": [
  {
   "url": "https://api.xmoo.app"
  }
 ],
 "paths": {
  "/v1/electrical/cable/size": {
   "post": {
    "summary": "Size a cable and its protective device",
    "description": "Design current → protective device → cross-section from current-carrying capacity → voltage drop → automatic disconnection → short-circuit withstand. The cross-section is increased automatically if voltage drop or disconnection require it (unless `crossSection` is given). Each step returns its formula lines with the values used and, if a condition fails, the next step to take.",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "de"
       ],
       "default": "en"
      },
      "description": "Language of descriptive texts (steps, errors). Field names are always English."
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CableSizeRequest"
       },
       "example": {
        "supply": "three-phase",
        "power": 50000,
        "powerFactor": 0.95,
        "length": 30,
        "installationMethod": "C",
        "ambientTemperature": 35,
        "protectiveDevice": "gG",
        "circuitType": "distribution",
        "upstreamImpedance": 100
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result with all steps",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CableSizeResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/electrical/current-capacity": {
   "post": {
    "summary": "Current-carrying capacity for one installation",
    "description": "Tabulated capacity Ir and corrected capacity Iz = Ir × f1 × f2 (× f3 in the ground) for all cross-sections of the column, one cross-section, or the smallest that carries `requiredCurrent`.",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "de"
       ],
       "default": "en"
      },
      "description": "Language of descriptive texts (steps, errors). Field names are always English."
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CapacityRequest"
       },
       "example": {
        "conductor": "aluminium",
        "insulation": "pvc-70",
        "installationMethod": "D",
        "loadedConductors": 3,
        "ambientTemperature": 25,
        "soilThermalResistivity": 1.5,
        "grouping": {
         "arrangement": "ducts-in-ground",
         "circuits": 3,
         "ductSpacing": 0.5
        },
        "requiredCurrent": 176.6
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Capacities",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/electrical/voltage-drop": {
   "post": {
    "summary": "Voltage drop of a cable",
    "description": "ΔU = 2·L·I·cos φ / (κ·A) single-phase, √3·L·I·cos φ / (κ·A) three-phase; κ = 56 (Cu) or 35 (Al) m/(Ω·mm²). Also the longest length within the limit and the smallest cross-section that keeps it.",
    "parameters": [
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "de"
       ],
       "default": "en"
      },
      "description": "Language of descriptive texts (steps, errors). Field names are always English."
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/VoltageDropRequest"
       },
       "example": {
        "supply": "single-phase",
        "current": 16,
        "length": 26,
        "crossSection": 2.5
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Voltage drop",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/electrical/tables": {
   "get": {
    "summary": "Allowed values",
    "description": "Installation methods, arrangements, groupings with their circuit counts, temperatures, protective devices and rated currents, cross-sections.",
    "responses": {
     "200": {
      "description": "Allowed values",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "CableSizeRequest": {
    "type": "object",
    "required": [
     "supply",
     "length",
     "installationMethod",
     "protectiveDevice",
     "circuitType"
    ],
    "properties": {
     "supply": {
      "type": "string",
      "enum": [
       "single-phase",
       "three-phase"
      ],
      "description": "230 V (U0) or 400 V."
     },
     "current": {
      "type": "number",
      "description": "Design current Ib in A. Give either current or power."
     },
     "power": {
      "type": "number",
      "description": "Power in W; Ib is calculated with powerFactor."
     },
     "powerFactor": {
      "type": "number",
      "description": "cos φ, default 1.",
      "exclusiveMinimum": 0,
      "maximum": 1
     },
     "length": {
      "type": "number",
      "description": "Single cable length in m (one way)."
     },
     "conductor": {
      "type": "string",
      "enum": [
       "copper",
       "aluminium"
      ],
      "default": "copper",
      "description": "Aluminium from 25 mm² (DIN VDE 0298-4 tables)."
     },
     "insulation": {
      "type": "string",
      "enum": [
       "pvc-70",
       "xlpe-90"
      ],
      "default": "pvc-70",
      "description": "pvc-70: PVC, 70 °C at the conductor (Tables 3/4). xlpe-90: cross-linked (XLPE, EPR), 90 °C (Tables 5/6)."
     },
     "installationMethod": {
      "type": "string",
      "enum": [
       "A1",
       "A2",
       "B1",
       "B2",
       "C",
       "D",
       "E",
       "F",
       "G"
      ],
      "description": "Reference installation method to IEC 60364-5-52 / DIN VDE 0298-4 Table 2. See GET /v1/electrical/tables."
     },
     "arrangement": {
      "type": "string",
      "enum": [
       "flat",
       "trefoil",
       "horizontal",
       "vertical"
      ],
      "description": "F (three-phase): flat or trefoil, default flat. G: horizontal or vertical, default horizontal."
     },
     "ambientTemperature": {
      "type": "number",
      "description": "Ambient air temperature in °C (default 30), or ground temperature for method D (default 20). Values from Tables 17/20, see /tables."
     },
     "soilThermalResistivity": {
      "type": "number",
      "description": "Method D only: 1, 1.5, 2, 2.5 (default) or 3 K·m/W (Table 21)."
     },
     "grouping": {
      "type": "object",
      "description": "Omit for a single circuit (factor 1).",
      "properties": {
       "arrangement": {
        "type": "string",
        "enum": [
         "bunched",
         "wall-touching",
         "wall-spaced",
         "ceiling-touching",
         "ceiling-spaced",
         "tray-unperforated-touching",
         "tray-perforated-touching",
         "tray-perforated-spaced",
         "tray-vertical-touching",
         "tray-vertical-spaced",
         "ladder-touching",
         "ladder-spaced",
         "single-core-tray-flat",
         "single-core-tray-vertical-flat",
         "single-core-ladder-flat",
         "single-core-tray-trefoil",
         "single-core-tray-vertical-trefoil",
         "single-core-ladder-trefoil",
         "ducts-in-ground"
        ],
        "description": "Tables 22–26. Single-core groupings apply to F/G, ducts-in-ground to D only."
       },
       "circuits": {
        "type": "integer",
        "minimum": 1,
        "default": 1,
        "description": "Number of circuits or multi-core cables. Between two table columns the next larger one (smaller factor) is used."
       },
       "tiers": {
        "type": "integer",
        "description": "Trays or ladders one above the other (Tables 23/24), default 1."
       },
       "ductSpacing": {
        "type": "number",
        "enum": [
         0,
         0.25,
         0.5,
         1
        ],
        "description": "ducts-in-ground: spacing between ducts in m (Table 26), default 0 (touching)."
       },
       "factor": {
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1,
        "description": "Own grouping factor instead of the table."
       }
      }
     },
     "protectiveDevice": {
      "type": "string",
      "enum": [
       "mcb-b",
       "mcb-c",
       "mcb-d",
       "gG"
      ]
     },
     "ratedCurrent": {
      "type": "number",
      "description": "Fixed rated current In; otherwise the smallest In ≥ Ib of the range."
     },
     "fuseI2Factor": {
      "type": "number",
      "enum": [
       1.6,
       1.45
      ],
      "default": 1.6,
      "description": "gG only: conventional fusing current I2 = 1.6 × In (IEC 60269) or 1.45 × In with manufacturer’s statement."
     },
     "crossSection": {
      "type": "number",
      "description": "Fixed cross-section in mm² to check instead of choosing one."
     },
     "earthingSystem": {
      "type": "string",
      "enum": [
       "TN",
       "TT"
      ],
      "default": "TN"
     },
     "circuitType": {
      "type": "string",
      "enum": [
       "socket-outlets",
       "fixed-equipment",
       "distribution"
      ],
      "description": "Sets the maximum disconnection time (IEC 60364-4-41 Table 41.1)."
     },
     "upstreamImpedance": {
      "type": "number",
      "description": "Fault loop impedance up to the origin of the circuit (Zv) in mΩ. Without it, automatic disconnection stays `incomplete`."
     },
     "voltageDropLimit": {
      "type": "number",
      "description": "Limit in %, default 4."
     }
    }
   },
   "CapacityRequest": {
    "type": "object",
    "required": [
     "installationMethod",
     "loadedConductors"
    ],
    "properties": {
     "conductor": {
      "type": "string",
      "enum": [
       "copper",
       "aluminium"
      ],
      "default": "copper",
      "description": "Aluminium from 25 mm² (DIN VDE 0298-4 tables)."
     },
     "insulation": {
      "type": "string",
      "enum": [
       "pvc-70",
       "xlpe-90"
      ],
      "default": "pvc-70",
      "description": "pvc-70: PVC, 70 °C at the conductor (Tables 3/4). xlpe-90: cross-linked (XLPE, EPR), 90 °C (Tables 5/6)."
     },
     "installationMethod": {
      "type": "string",
      "enum": [
       "A1",
       "A2",
       "B1",
       "B2",
       "C",
       "D",
       "E",
       "F",
       "G"
      ],
      "description": "Reference installation method to IEC 60364-5-52 / DIN VDE 0298-4 Table 2. See GET /v1/electrical/tables."
     },
     "arrangement": {
      "type": "string",
      "enum": [
       "flat",
       "trefoil",
       "horizontal",
       "vertical"
      ],
      "description": "F (three-phase): flat or trefoil, default flat. G: horizontal or vertical, default horizontal."
     },
     "ambientTemperature": {
      "type": "number",
      "description": "Ambient air temperature in °C (default 30), or ground temperature for method D (default 20). Values from Tables 17/20, see /tables."
     },
     "soilThermalResistivity": {
      "type": "number",
      "description": "Method D only: 1, 1.5, 2, 2.5 (default) or 3 K·m/W (Table 21)."
     },
     "grouping": {
      "type": "object",
      "description": "Omit for a single circuit (factor 1).",
      "properties": {
       "arrangement": {
        "type": "string",
        "enum": [
         "bunched",
         "wall-touching",
         "wall-spaced",
         "ceiling-touching",
         "ceiling-spaced",
         "tray-unperforated-touching",
         "tray-perforated-touching",
         "tray-perforated-spaced",
         "tray-vertical-touching",
         "tray-vertical-spaced",
         "ladder-touching",
         "ladder-spaced",
         "single-core-tray-flat",
         "single-core-tray-vertical-flat",
         "single-core-ladder-flat",
         "single-core-tray-trefoil",
         "single-core-tray-vertical-trefoil",
         "single-core-ladder-trefoil",
         "ducts-in-ground"
        ],
        "description": "Tables 22–26. Single-core groupings apply to F/G, ducts-in-ground to D only."
       },
       "circuits": {
        "type": "integer",
        "minimum": 1,
        "default": 1,
        "description": "Number of circuits or multi-core cables. Between two table columns the next larger one (smaller factor) is used."
       },
       "tiers": {
        "type": "integer",
        "description": "Trays or ladders one above the other (Tables 23/24), default 1."
       },
       "ductSpacing": {
        "type": "number",
        "enum": [
         0,
         0.25,
         0.5,
         1
        ],
        "description": "ducts-in-ground: spacing between ducts in m (Table 26), default 0 (touching)."
       },
       "factor": {
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1,
        "description": "Own grouping factor instead of the table."
       }
      }
     },
     "loadedConductors": {
      "type": "integer",
      "enum": [
       2,
       3
      ]
     },
     "crossSection": {
      "type": "number",
      "description": "Only this cross-section."
     },
     "requiredCurrent": {
      "type": "number",
      "description": "Return the smallest cross-section with Iz ≥ this current."
     }
    }
   },
   "VoltageDropRequest": {
    "type": "object",
    "required": [
     "supply",
     "length",
     "crossSection"
    ],
    "properties": {
     "supply": {
      "type": "string",
      "enum": [
       "single-phase",
       "three-phase"
      ]
     },
     "current": {
      "type": "number",
      "description": "Current in A (or power)."
     },
     "power": {
      "type": "number",
      "description": "Power in W."
     },
     "powerFactor": {
      "type": "number",
      "description": "cos φ, default 1."
     },
     "length": {
      "type": "number",
      "description": "Single length in m."
     },
     "crossSection": {
      "type": "number",
      "description": "mm²"
     },
     "conductor": {
      "type": "string",
      "enum": [
       "copper",
       "aluminium"
      ],
      "default": "copper"
     },
     "voltageDropLimit": {
      "type": "number",
      "description": "Limit in %, default 4."
     }
    }
   },
   "Step": {
    "type": "object",
    "properties": {
     "step": {
      "type": "integer"
     },
     "title": {
      "type": "string"
     },
     "standard": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "ok",
       "failed",
       "incomplete",
       "note"
      ]
     },
     "lines": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "nextStep": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "CableSizeResponse": {
    "type": "object",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "ok",
       "failed",
       "incomplete",
       "note"
      ],
      "description": "failed: a condition is not met (see the step's nextStep); incomplete: a step could not be checked (e.g. no upstreamImpedance); note: met, but the short-circuit check needs a manufacturer value."
     },
     "result": {
      "type": "object"
     },
     "sources": {
      "type": "object"
     },
     "steps": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Step"
      }
     },
     "notice": {
      "type": "string"
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "field": {
        "type": "string"
       },
       "errors": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "responses": {
   "BadRequest": {
    "description": "Body is not a JSON object or `lang` is invalid",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "Unauthorized": {
    "description": "Not called through RapidAPI",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  }
 }
}