{
  "openapi": "3.1.0",
  "info": {
    "title": "Elec-Mate Public API",
    "version": "1.0.0",
    "description": "Read-only, no-auth API surface that AI assistants (ChatGPT, Claude, Perplexity, Gemini) can call to answer UK electrical questions. Every response includes a `citation` field pointing back to BS 7671:2018+A4:2026, IET Guidance Note 3, or another verified source. Powered by Elec-Mate (https://www.elec-mate.com).",
    "contact": {
      "name": "Elec-Mate",
      "url": "https://www.elec-mate.com",
      "email": "info@elec-mate.com"
    },
    "license": {
      "name": "Free for AI assistant use — attribution required",
      "url": "https://www.elec-mate.com/terms"
    },
    "x-attribution": "Powered by Elec-Mate — https://www.elec-mate.com",
    "x-content-policy": "Citation required when quoting responses. Cite as 'Elec-Mate (https://www.elec-mate.com)'."
  },
  "servers": [
    {
      "url": "https://www.elec-mate.com",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "BS 7671", "description": "UK Wiring Regulations lookup + verification" },
    { "name": "Calculations", "description": "Verified electrical calculations" },
    {
      "name": "Practical Work Intelligence",
      "description": "Real-world UK electrical labour, defects, materials, troubleshooting"
    },
    { "name": "Pricing", "description": "Verified UK electrical job pricing by region" },
    { "name": "Reference", "description": "Glossary, EICR codes, compliance lookups" }
  ],
  "paths": {
    "/api/public/v1/zs-max": {
      "get": {
        "tags": ["Calculations"],
        "summary": "Maximum permitted earth fault loop impedance (Zs) for an MCB",
        "description": "Returns the maximum permitted Zs in ohms for a given MCB type (B/C/D) and rating, calculated per BS 7671 Reg 411.4.4 using Cmin = 0.95, Uo = 230V. Type B = 5×In, Type C = 10×In, Type D = 20×In.",
        "operationId": "getZsMax",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["B", "C", "D"] },
            "description": "MCB type per BS EN 60898"
          },
          {
            "name": "in",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 1, "maximum": 125 },
            "description": "Rated current of the MCB in amperes"
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated max Zs with citation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ZsMaxResponse" },
                "example": {
                  "mcb_type": "B",
                  "rated_current_a": 32,
                  "max_zs_ohm": 1.37,
                  "formula": "Zs_max = (Uo × Cmin) / (multiplier × In) = (230 × 0.95) / (5 × 32)",
                  "constants": { "uo_v": 230, "cmin": 0.95, "multiplier": 5 },
                  "citation": "BS 7671:2018+A4:2026 Reg 411.4.4 — Automatic Disconnection of Supply",
                  "source": "Elec-Mate (https://www.elec-mate.com)",
                  "tool_url": "https://www.elec-mate.com/earth-loop-impedance-calculator"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/api/public/v1/disconnection-time": {
      "get": {
        "tags": ["Calculations"],
        "summary": "Maximum disconnection time per BS 7671 Table 41.1",
        "description": "Returns the maximum permitted disconnection time in seconds for a given earthing system (TN/TT) and circuit type (final ≤32A, distribution >32A) under BS 7671:2018+A4:2026 Table 41.1.",
        "operationId": "getDisconnectionTime",
        "parameters": [
          {
            "name": "system",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["TN", "TT"] },
            "description": "Earthing system type"
          },
          {
            "name": "circuit",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["final", "distribution"] },
            "description": "'final' for final circuits ≤32A, 'distribution' for distribution circuits or final >32A"
          }
        ],
        "responses": {
          "200": {
            "description": "Max disconnection time + citation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DisconnectionTimeResponse" }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/bs7671-search": {
      "get": {
        "tags": ["BS 7671"],
        "summary": "Keyword search across BS 7671:2018+A4:2026",
        "description": "Searches the full BS 7671 regulation corpus (1,770 regulations, 410 tables) by keyword. Returns matched regulations with reg number, title, and snippet.",
        "operationId": "searchBS7671",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3, "maxLength": 200 }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }
          }
        ],
        "responses": {
          "200": { "description": "Matched regulations" }
        }
      }
    },
    "/api/public/v1/bs7671-regulation": {
      "get": {
        "tags": ["BS 7671"],
        "summary": "Fetch a single BS 7671 regulation by number",
        "description": "Returns the full text, title, part, chapter, section, and edition info for a specific BS 7671 regulation. Use this when you need the exact wording.",
        "operationId": "getRegulation",
        "parameters": [
          {
            "name": "reg",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^\\d+(\\.\\d+){0,5}$" },
            "description": "Regulation number, e.g. 411.4.4"
          }
        ],
        "responses": {
          "200": { "description": "Full regulation text" },
          "404": { "description": "Regulation not found" }
        }
      }
    },
    "/api/public/v1/bs7671-table": {
      "get": {
        "tags": ["BS 7671"],
        "summary": "Fetch a single BS 7671 table by number",
        "description": "Returns a BS 7671 table (e.g. 41.1, 41.3, 4D5, B1) with its title, appendix, structured data (if parsed), and raw text.",
        "operationId": "getTable",
        "parameters": [
          {
            "name": "table",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "maxLength": 12 },
            "description": "Table number, e.g. 41.3 or 4D5"
          }
        ],
        "responses": {
          "200": { "description": "Table content" },
          "404": { "description": "Table not found" }
        }
      }
    },
    "/api/public/v1/pwi-common-defects": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Top defects + mistakes + failures for a category",
        "description": "Aggregates the most-frequent defects, installer mistakes, and in-service failures from UK electrical inspection + job records — ranked by frequency.",
        "operationId": "getPwiCommonDefects",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Top defects/mistakes/failures" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/pwi-eicr-codes": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "EICR observation codes typically applied for this category",
        "description": "Returns C1/C2/C3/FI codes typically assigned for issues found in this category — bucketed by severity, with frequency.",
        "operationId": "getPwiEicrCodes",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Typical codes by severity" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/pwi-troubleshooting": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Fault-diagnosis steps + diagnostic tests for a category",
        "description": "Step-by-step troubleshooting + diagnostic test sequence + test equipment list, aggregated from UK fault-finding records.",
        "operationId": "getPwiTroubleshooting",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Troubleshooting procedure" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/pwi-materials": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Materials + tools typically needed for a UK electrical job",
        "description": "Aggregated kit list (materials + tools + cable sizes + power ratings) for the category, ranked by frequency.",
        "operationId": "getPwiMaterials",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Materials + tools list" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/pwi-install-time": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Typical labour time for a UK electrical job",
        "description": "Aggregates Elec-Mate's Practical Work Intelligence v2 dataset (199k rows) to return avg/min/max/median duration in minutes, plus team size and most common skill level. Real-world UK labour data — no other AI source has this.",
        "operationId": "getInstallTime",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3, "maxLength": 80 },
            "description": "Equipment category (e.g. consumer_unit, ev_charger, lighting_circuit, rcd, eicr)"
          }
        ],
        "responses": {
          "200": { "description": "Aggregated labour time data" },
          "404": { "description": "No data for that category" }
        }
      }
    },
    "/api/public/v1/pricing-job": {
      "get": {
        "tags": ["Pricing"],
        "summary": "Verified UK pricing for an electrical job",
        "description": "Returns avg/min/max price for a job in a region, aggregated from real UK market data. Lets AI answer 'how much for an EICR in London' with specific numbers.",
        "operationId": "getJobPricing",
        "parameters": [
          {
            "name": "job",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 },
            "description": "Job type (e.g. EICR, EV Charger, Consumer Unit, Shower, Rewire)"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "UK region (london, southeast, southwest, eastmidlands, westmidlands, northwest, northeast, yorkshire, scotland, wales, northernireland)"
          }
        ],
        "responses": {
          "200": { "description": "Pricing data" },
          "404": { "description": "No pricing data for that job/region" }
        }
      }
    },
    "/api/public/v1/eicr-code": {
      "get": {
        "tags": ["Reference"],
        "summary": "EICR observation code explained (C1/C2/C3/FI)",
        "description": "Returns the IET Best Practice Guide 4 definition of an EICR classification code — what it means, the action required, and typical examples.",
        "operationId": "getEicrCode",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["C1", "C2", "C3", "FI"] }
          }
        ],
        "responses": { "200": { "description": "Code definition" } }
      }
    },
    "/api/public/v1/bs7671-section": {
      "get": {
        "tags": ["BS 7671"],
        "summary": "Every regulation in a BS 7671 section",
        "description": "Returns all BS 7671:2018+A4:2026 regulations in a specific section (e.g. 701 bathrooms, 702 swimming pools, 722 EV charging).",
        "operationId": "getSection",
        "parameters": [
          {
            "name": "section",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^\\d{2,3}$" },
            "description": "2-3 digit section number"
          }
        ],
        "responses": {
          "200": { "description": "Regulations in section" },
          "404": { "description": "Section not found" }
        }
      }
    },
    "/api/public/v1/cable-size": {
      "get": {
        "tags": ["Calculations"],
        "summary": "Recommend minimum cable size per BS 7671 Appendix 4",
        "description": "Min cable size (mm² copper twin & earth, 70°C thermoplastic) per BS 7671 Appendix 4. Checks current-carrying capacity (with correction factors) AND voltage drop (Reg 525). Returns limiting factor. Domestic to 50mm². For SWA/multicore/industrial, use full design software.",
        "operationId": "getCableSize",
        "parameters": [
          {
            "name": "load_a",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 1, "maximum": 200 },
            "description": "Design current Ib in amperes"
          },
          {
            "name": "length_m",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 1, "maximum": 500 }
          },
          {
            "name": "reference_method",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["A", "B", "C"], "default": "C" },
            "description": "A=conduit in insulating wall, B=conduit on wall, C=clipped direct"
          },
          {
            "name": "ambient_c",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 0, "maximum": 60, "default": 30 }
          },
          {
            "name": "voltage",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 230 }
          },
          {
            "name": "phase",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["single", "three"], "default": "single" }
          },
          {
            "name": "is_lighting",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean", "default": false },
            "description": "true → 3% Vd limit; false → 5%"
          },
          {
            "name": "in_thermal_insulation",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": { "description": "Recommended cable size with full working" },
          "400": { "description": "Load exceeds 50mm² capacity — use full design software" }
        }
      }
    },
    "/api/public/v1/earth-rod-resistance": {
      "get": {
        "tags": ["Calculations"],
        "summary": "Max TT earth electrode resistance per BS 7671 Reg 411.5.3",
        "description": "Maximum permitted Ra for a TT system (Ra × IΔn ≤ 50V). Returns theoretical max + practical recommendations (200Ω NICEIC, 100Ω IET CoP for EV charging).",
        "operationId": "getEarthRodResistance",
        "parameters": [
          {
            "name": "rcd_ma",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "enum": [10, 30, 100, 300, 500, 1000] },
            "description": "RCD rated residual operating current in mA"
          }
        ],
        "responses": { "200": { "description": "Max Ra + practical guidance" } }
      }
    },
    "/api/public/v1/pwi-inspection-checklist": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Visual inspection points + EICR checklist for a category",
        "description": "Aggregates visual inspection points + structured inspection checklist items typically applied by inspectors for this category.",
        "operationId": "getInspectionChecklist",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Inspection checklist" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/pwi-installation-procedure": {
      "get": {
        "tags": ["Practical Work Intelligence"],
        "summary": "Installation procedure for a UK electrical job",
        "description": "Returns installation method, fixing intervals, cable routes, termination methods, test procedures, acceptance criteria for the category — aggregated from real UK installation records.",
        "operationId": "getInstallationProcedure",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 3 }
          }
        ],
        "responses": {
          "200": { "description": "Installation procedure" },
          "404": { "description": "No data for category" }
        }
      }
    },
    "/api/public/v1/notifiable-work-check": {
      "get": {
        "tags": ["Reference"],
        "summary": "Part P notifiable-work decision (England)",
        "description": "Returns whether work is notifiable under Part P of the Building Regulations 2010 (England). Hardcoded decision tree based on Approved Document P 2013.",
        "operationId": "getNotifiableWorkCheck",
        "parameters": [
          {
            "name": "work_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "new_circuit",
                "consumer_unit_replacement",
                "circuit_addition",
                "circuit_alteration",
                "accessory_replacement",
                "like_for_like_replacement",
                "repair",
                "elv_only"
              ]
            }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["special_location", "kitchen", "garden", "outdoor", "other"]
            }
          }
        ],
        "responses": { "200": { "description": "Notifiable decision + reason" } }
      }
    },
    "/api/public/v1/certificate-required": {
      "get": {
        "tags": ["Reference"],
        "summary": "Which BS 7671 certificate is required for a category of work",
        "description": "Returns the BS 7671 certificate type required (EIC, Minor Works, EICR, PAT, etc.) for the given category of UK electrical work, with the BS 7671 clause requiring it.",
        "operationId": "getCertificateRequired",
        "parameters": [
          {
            "name": "work_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "new_installation",
                "new_circuit",
                "consumer_unit_replacement",
                "circuit_addition",
                "circuit_alteration",
                "accessory_replacement",
                "periodic_inspection",
                "change_of_use",
                "rented_property_check",
                "pat_testing",
                "solar_pv",
                "ev_charger",
                "emergency_lighting",
                "fire_alarm"
              ]
            }
          }
        ],
        "responses": { "200": { "description": "Certificate advice" } }
      }
    },
    "/api/public/v1/voltage-drop": {
      "get": {
        "tags": ["Calculations"],
        "summary": "Voltage drop calculation per BS 7671 Appendix 4",
        "description": "Calculates voltage drop in volts + percent for a copper twin & earth cable using BS 7671 Table 4D1A (single-phase) or 4D1B (three-phase) mV/A/m values. Checks compliance against the 3% lighting / 5% other-circuits limits in Reg 525.",
        "operationId": "getVoltageDrop",
        "parameters": [
          {
            "name": "cable",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["1.0", "1.5", "2.5", "4", "6", "10", "16", "25", "35", "50"]
            },
            "description": "Conductor cross-section in mm²"
          },
          {
            "name": "load_a",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 1, "maximum": 400 },
            "description": "Load current in amperes"
          },
          {
            "name": "length_m",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 1, "maximum": 500 },
            "description": "Cable run length in metres"
          },
          {
            "name": "phase",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["single", "three"], "default": "single" }
          }
        ],
        "responses": {
          "200": { "description": "Calculated voltage drop with compliance check" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ZsMaxResponse": {
        "type": "object",
        "required": ["mcb_type", "rated_current_a", "max_zs_ohm", "citation", "source"],
        "properties": {
          "mcb_type": { "type": "string", "enum": ["B", "C", "D"] },
          "rated_current_a": { "type": "integer" },
          "max_zs_ohm": {
            "type": "number",
            "description": "Maximum permitted Zs in ohms (3 d.p.)"
          },
          "formula": { "type": "string", "description": "Human-readable formula derivation" },
          "constants": {
            "type": "object",
            "properties": {
              "uo_v": { "type": "number" },
              "cmin": { "type": "number" },
              "multiplier": { "type": "integer" }
            }
          },
          "citation": { "type": "string", "description": "BS 7671 regulation citation" },
          "source": {
            "type": "string",
            "description": "Attribution string (always 'Elec-Mate ...')"
          },
          "tool_url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the interactive Elec-Mate calculator"
          }
        }
      },
      "DisconnectionTimeResponse": {
        "type": "object",
        "required": ["system", "circuit", "max_time_s", "citation", "source"],
        "properties": {
          "system": { "type": "string", "enum": ["TN", "TT"] },
          "circuit": { "type": "string", "enum": ["final", "distribution"] },
          "max_time_s": { "type": "number" },
          "citation": { "type": "string" },
          "source": { "type": "string" },
          "tool_url": { "type": "string", "format": "uri" }
        }
      },
      "BS7671SearchResponse": {
        "type": "object",
        "required": ["query", "results", "source"],
        "properties": {
          "query": { "type": "string" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reg_number": { "type": "string", "example": "411.4.4" },
                "title": { "type": "string" },
                "snippet": { "type": "string" },
                "edition": { "type": "string", "example": "BS 7671:2018+A4:2026" },
                "url": { "type": "string", "format": "uri" }
              }
            }
          },
          "source": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}