{
  "openapi": "3.1.1",
  "info": {
    "title": "KiCad Netlist Exporter API",
    "version": "1.0.0",
    "summary": "Turn an Ohmforge schematic into a KiCad netlist (.net)",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://ohmforgekicadnetlist.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Turn an Ohmforge schematic into a KiCad netlist (.net)",
        "description": "Export an Ohmforge schematic as a KiCad S-expression netlist with components, footprints, typed pins and nets, ready to import into the KiCad PCB editor.\n\nMethodology:\n- Resolves nets with the same connectivity as the Ohmforge workspace (wires, T-junctions, net labels, ground).\n- Writes KiCad's S-expression netlist, export version \"E\": a design header, one comp per component (ref, value, optional footprint, libsource, sheetpath, a stable tstamps UUID derived from project name and reference), one libpart per symbol kind with numbered, typed pins, and one net per resolved net with its nodes (ref, pin, pinfunction, pintype).\n- Ground becomes the net GND and labelled nets keep their label; other nets are named Net-(REF-PIN) after their first node, or unconnected-(REF-PIN) for a single pin. Codes are assigned after sorting by name.\n- Pin numbers: two-terminal parts 1/2 in drawing order, diodes and LEDs K = 1 and A = 2, transistors B/C/E and G/D/S = 1/2/3, the 555 timer in DIP-8 order, other symbols in their pin order. Pin types come from the typed-pin ERC catalog.\n- Strings are quoted with backslash escapes as in KiCad files. Ground symbols and net labels are not components; instruments are excluded unless requested.\n\nLibraries are referenced as \"ohmforge\" and pin numbers follow the convention above; check that every footprint's pad numbers match these pins (especially transistors and ICs) before ordering boards.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "ohmforge_kicad_netlist",
        "x-owner-app": "ohmforge",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OhmforgeKicadNetlistInput"
              },
              "examples": {
                "example1": {
                  "summary": "Battery, resistor and LED with footprints",
                  "value": {
                    "project": "{\n  \"format\": \"ohmforge\",\n  \"version\": 1,\n  \"name\": \"LED on 9 V\",\n  \"parts\": [\n    {\n      \"id\": \"BT1\",\n      \"kind\": \"battery\",\n      \"x\": 0,\n      \"y\": 0,\n      \"props\": {\n        \"footprint\": \"Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical\"\n      }\n    },\n    {\n      \"id\": \"R1\",\n      \"kind\": \"resistor\",\n      \"x\": 4,\n      \"y\": -2,\n      \"props\": {\n        \"value\": \"470\",\n        \"footprint\": \"Resistor_THT:R_Axial_DIN0207_L6.3mm_D2.5mm_P10.16mm_Horizontal\"\n      }\n    },\n    {\n      \"id\": \"D1\",\n      \"kind\": \"led\",\n      \"x\": 8,\n      \"y\": 0,\n      \"rot\": 90,\n      \"props\": {\n        \"footprint\": \"LED_THT:LED_D5.0mm\"\n      }\n    },\n    {\n      \"id\": \"GND1\",\n      \"kind\": \"ground\",\n      \"x\": 0,\n      \"y\": 4\n    }\n  ],\n  \"wires\": [\n    {\n      \"id\": \"w1\",\n      \"pts\": [\n        [\n          0,\n          -2\n        ],\n        [\n          2,\n          -2\n        ]\n      ]\n    },\n    {\n      \"id\": \"w2\",\n      \"pts\": [\n        [\n          6,\n          -2\n        ],\n        [\n          8,\n          -2\n        ]\n      ]\n    },\n    {\n      \"id\": \"w3\",\n      \"pts\": [\n        [\n          8,\n          2\n        ],\n        [\n          8,\n          4\n        ],\n        [\n          0,\n          4\n        ]\n      ]\n    },\n    {\n      \"id\": \"w4\",\n      \"pts\": [\n        [\n          0,\n          2\n        ],\n        [\n          0,\n          4\n        ]\n      ]\n    }\n  ]\n}"
                  }
                },
                "example2": {
                  "summary": "Logic gates without footprints",
                  "value": {
                    "project": "{\n  \"format\": \"ohmforge\",\n  \"version\": 1,\n  \"name\": \"Two inverters fighting\",\n  \"parts\": [\n    {\n      \"id\": \"U1\",\n      \"kind\": \"not\",\n      \"x\": 0,\n      \"y\": 0\n    },\n    {\n      \"id\": \"U2\",\n      \"kind\": \"not\",\n      \"x\": 0,\n      \"y\": 6\n    },\n    {\n      \"id\": \"U3\",\n      \"kind\": \"and\",\n      \"x\": 12,\n      \"y\": 1\n    }\n  ],\n  \"wires\": [\n    {\n      \"id\": \"w1\",\n      \"pts\": [\n        [\n          3,\n          0\n        ],\n        [\n          9,\n          0\n        ]\n      ]\n    },\n    {\n      \"id\": \"w2\",\n      \"pts\": [\n        [\n          3,\n          6\n        ],\n        [\n          6,\n          6\n        ],\n        [\n          6,\n          0\n        ]\n      ]\n    }\n  ]\n}"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OhmforgeKicadNetlistResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "OhmforgeKicadNetlistInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "project": {
            "title": "Ohmforge project JSON",
            "description": "Paste an exported .ohmforge.json project (at most 200 parts and 200 wires). A part property \"footprint\" (\"Library:Footprint\") is written to the netlist.",
            "type": "string",
            "maxLength": 200000,
            "default": "{\n  \"format\": \"ohmforge\",\n  \"version\": 1,\n  \"name\": \"LED on 9 V\",\n  \"parts\": [\n    {\n      \"id\": \"BT1\",\n      \"kind\": \"battery\",\n      \"x\": 0,\n      \"y\": 0,\n      \"props\": {\n        \"footprint\": \"Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical\"\n      }\n    },\n    {\n      \"id\": \"R1\",\n      \"kind\": \"resistor\",\n      \"x\": 4,\n      \"y\": -2,\n      \"props\": {\n        \"value\": \"470\",\n        \"footprint\": \"Resistor_THT:R_Axial_DIN0207_L6.3mm_D2.5mm_P10.16mm_Horizontal\"\n      }\n    },\n    {\n      \"id\": \"D1\",\n      \"kind\": \"led\",\n      \"x\": 8,\n      \"y\": 0,\n      \"rot\": 90,\n      \"props\": {\n        \"footprint\": \"LED_THT:LED_D5.0mm\"\n      }\n    },\n    {\n      \"id\": \"GND1\",\n      \"kind\": \"ground\",\n      \"x\": 0,\n      \"y\": 4\n    }\n  ],\n  \"wires\": [\n    {\n      \"id\": \"w1\",\n      \"pts\": [\n        [\n          0,\n          -2\n        ],\n        [\n          2,\n          -2\n        ]\n      ]\n    },\n    {\n      \"id\": \"w2\",\n      \"pts\": [\n        [\n          6,\n          -2\n        ],\n        [\n          8,\n          -2\n        ]\n      ]\n    },\n    {\n      \"id\": \"w3\",\n      \"pts\": [\n        [\n          8,\n          2\n        ],\n        [\n          8,\n          4\n        ],\n        [\n          0,\n          4\n        ]\n      ]\n    },\n    {\n      \"id\": \"w4\",\n      \"pts\": [\n        [\n          0,\n          2\n        ],\n        [\n          0,\n          4\n        ]\n      ]\n    }\n  ]\n}"
          },
          "includeInstruments": {
            "title": "Include instruments",
            "description": "Bench supplies, function generators and logic probes are not board parts and are left out unless you tick this.",
            "type": "boolean",
            "default": false
          }
        },
        "required": []
      },
      "OhmforgeKicadNetlistResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "projectName",
              "format",
              "componentCount",
              "netCount",
              "components",
              "nets",
              "excluded",
              "warnings",
              "netlist"
            ],
            "properties": {
              "projectName": {
                "type": "string"
              },
              "format": {
                "type": "string",
                "const": "kicadsexpr E"
              },
              "componentCount": {
                "type": "integer",
                "minimum": 0
              },
              "netCount": {
                "type": "integer",
                "minimum": 0
              },
              "components": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "ref",
                    "value",
                    "footprint",
                    "kind",
                    "description",
                    "tstamp"
                  ],
                  "properties": {
                    "ref": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    },
                    "footprint": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "tstamp": {
                      "type": "string"
                    }
                  }
                }
              },
              "nets": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "code",
                    "name",
                    "nodes"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "name": {
                      "type": "string"
                    },
                    "nodes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "ref",
                          "pin",
                          "pintype"
                        ],
                        "properties": {
                          "ref": {
                            "type": "string"
                          },
                          "pin": {
                            "type": "string"
                          },
                          "pinfunction": {
                            "type": "string"
                          },
                          "pintype": {
                            "type": "string",
                            "enum": [
                              "input",
                              "output",
                              "bidirectional",
                              "tri_state",
                              "passive",
                              "unspecified",
                              "power_in",
                              "power_out",
                              "open_collector",
                              "open_emitter"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              },
              "excluded": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "netlist": {
                "type": "string"
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}