{
  "openapi": "3.0.0",
  "info": {
    "title": "Convematik API",
    "version": "1.1.0",
    "description": "HTTP API for unit conversions, catalog discovery, search, batch conversion, unit metadata and focused calculators."
  },
  "servers": [
    {
      "url": "https://api.convematik.com"
    },
    {
      "url": "http://localhost:8000"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "API is reachable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "status": "ok"
                }
              }
            }
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "summary": "Describe API and product capabilities",
        "responses": {
          "200": {
            "description": "Capabilities, endpoint list, feature states and generated tool counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "status": "ok",
                  "version": "1.1.0",
                  "toolCount": 139,
                  "endpoints": [
                    "/health",
                    "/capabilities",
                    "/tools"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/tools": {
      "get": {
        "summary": "List generated Convematik tools",
        "responses": {
          "200": {
            "description": "Tool catalog and categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search Convematik tool pages",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "example": "kg"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "example": "Mass"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results, limited to 20 items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Missing query/category or invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/convert": {
      "get": {
        "summary": "Convert between units",
        "parameters": [
          {
            "name": "value",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 78
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "kg"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "lb"
          },
          {
            "name": "ingredient",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "example": "flour"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "value": 78.0,
                  "from": "kg",
                  "to": "lb",
                  "result": 171.9605645042045
                }
              }
            }
          },
          "400": {
            "description": "Invalid numeric value, unknown unit or incompatible categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/batch": {
      "post": {
        "summary": "Perform multiple conversions in one request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "conversions": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "number"
                        },
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "value",
                        "from",
                        "to"
                      ]
                    }
                  }
                },
                "required": [
                  "conversions"
                ]
              },
              "example": {
                "conversions": [
                  {
                    "value": 1,
                    "from": "kg",
                    "to": "lb"
                  },
                  {
                    "value": 5,
                    "from": "m",
                    "to": "ft"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of conversion results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing fields or more than 100 conversions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/roman": {
      "get": {
        "summary": "Convert Roman numerals to integers and vice versa",
        "parameters": [
          {
            "name": "roman",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "example": "XIV"
          },
          {
            "name": "integer",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "required": false,
            "example": 2026
          }
        ],
        "responses": {
          "200": {
            "description": "Roman/integer conversion result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "roman": "XIV",
                  "integer": 14
                }
              }
            }
          },
          "400": {
            "description": "Invalid Roman numeral or integer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/fraction": {
      "get": {
        "summary": "Perform operations on fractions",
        "parameters": [
          {
            "name": "numerator",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "example": 42
          },
          {
            "name": "denominator",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "example": 56
          },
          {
            "name": "op",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "simplify",
                "decimal",
                "percent"
              ]
            },
            "required": false,
            "example": "simplify"
          }
        ],
        "responses": {
          "200": {
            "description": "Fraction operation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "numerator": 42,
                  "denominator": 56,
                  "operation": "simplify",
                  "result": {
                    "numerator": 3,
                    "denominator": 4
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid fraction or operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/table": {
      "get": {
        "summary": "Generate a conversion table",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "kg"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "lb"
          },
          {
            "name": "start",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 1
          },
          {
            "name": "end",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 10
          },
          {
            "name": "step",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion table",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid table parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/bmi": {
      "get": {
        "summary": "Calculate body mass index",
        "parameters": [
          {
            "name": "weight",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 70
          },
          {
            "name": "height",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 1.75
          },
          {
            "name": "unit",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "metric",
                "imperial"
              ]
            },
            "required": false,
            "example": "metric"
          }
        ],
        "responses": {
          "200": {
            "description": "BMI result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "weight": 70,
                  "height": 1.75,
                  "unit": "metric",
                  "bmi": 22.86,
                  "category": "healthy"
                }
              }
            }
          },
          "400": {
            "description": "Invalid BMI parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/electrical": {
      "get": {
        "summary": "Calculate watts, amps or volts",
        "parameters": [
          {
            "name": "watts",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 1200
          },
          {
            "name": "amps",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 10
          },
          {
            "name": "volts",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 120
          },
          {
            "name": "target",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "watts",
                "amps",
                "volts"
              ]
            },
            "required": false,
            "example": "amps"
          }
        ],
        "responses": {
          "200": {
            "description": "Electrical calculation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "target": "amps",
                  "result": 10.0
                }
              }
            }
          },
          "400": {
            "description": "Invalid electrical parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/percentage": {
      "get": {
        "summary": "Calculate percentage values",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "percent-of",
                "percent-change",
                "share"
              ]
            },
            "required": false,
            "example": "percent-of"
          },
          {
            "name": "x",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 20
          },
          {
            "name": "y",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 150
          }
        ],
        "responses": {
          "200": {
            "description": "Percentage calculation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "mode": "percent-of",
                  "result": 30.0
                }
              }
            }
          },
          "400": {
            "description": "Invalid percentage parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/age": {
      "get": {
        "summary": "Calculate exact age from a birth date",
        "parameters": [
          {
            "name": "birth_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": true,
            "example": "1990-01-15"
          },
          {
            "name": "as_of",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "example": "2026-06-12"
          }
        ],
        "responses": {
          "200": {
            "description": "Age in years, months and days",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid age parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/date-difference": {
      "get": {
        "summary": "Calculate days between two dates",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": true,
            "example": "2026-06-01"
          },
          {
            "name": "end",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": true,
            "example": "2026-06-12"
          },
          {
            "name": "inclusive",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "required": false,
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "Date difference result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "days": 11,
                  "inclusive": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid date difference parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/tip": {
      "get": {
        "summary": "Calculate tip, total and split amount",
        "parameters": [
          {
            "name": "subtotal",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 80
          },
          {
            "name": "tip_percent",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 20
          },
          {
            "name": "people",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "required": false,
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "Tip calculation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tip": 16.0,
                  "total": 96.0,
                  "perPerson": 48.0
                }
              }
            }
          },
          "400": {
            "description": "Invalid tip parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/discount": {
      "get": {
        "summary": "Calculate discount and optional tax",
        "parameters": [
          {
            "name": "price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 120
          },
          {
            "name": "discount_percent",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 25
          },
          {
            "name": "tax_percent",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": false,
            "example": 8
          }
        ],
        "responses": {
          "200": {
            "description": "Discount calculation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "discount": 30.0,
                  "total": 97.2
                }
              }
            }
          },
          "400": {
            "description": "Invalid discount parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/fuel-cost": {
      "get": {
        "summary": "Calculate trip fuel cost",
        "parameters": [
          {
            "name": "distance",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 240
          },
          {
            "name": "efficiency",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 30
          },
          {
            "name": "fuel_price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 3.75
          },
          {
            "name": "efficiency_unit",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mpg",
                "l/100km",
                "km/l"
              ]
            },
            "required": false,
            "example": "mpg"
          }
        ],
        "responses": {
          "200": {
            "description": "Fuel cost result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "fuelUsed": 8.0,
                  "cost": 30.0
                }
              }
            }
          },
          "400": {
            "description": "Invalid fuel cost parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/unit-price": {
      "get": {
        "summary": "Calculate price per unit",
        "parameters": [
          {
            "name": "price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 12.99
          },
          {
            "name": "quantity",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "required": true,
            "example": 3
          },
          {
            "name": "unit",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "example": "lb"
          }
        ],
        "responses": {
          "200": {
            "description": "Unit price result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "unitPrice": 4.33,
                  "unit": "lb"
                }
              }
            }
          },
          "400": {
            "description": "Invalid unit price parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "Invalid input"
                }
              }
            }
          }
        }
      }
    },
    "/units": {
      "get": {
        "summary": "List supported unit aliases and metadata by category",
        "responses": {
          "200": {
            "description": "Supported unit aliases and conversion metadata grouped by category",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "schemaVersion": 2,
                  "mass": [
                    "g",
                    "kg",
                    "lb"
                  ],
                  "categories": [
                    {
                      "name": "mass",
                      "kind": "linear",
                      "baseUnit": "kg",
                      "units": [
                        {
                          "id": "kg",
                          "aliases": [
                            "kg",
                            "kilogram",
                            "kilograms"
                          ],
                          "factorToBase": 1.0,
                          "toBaseScale": 1.0,
                          "toBaseOffset": 0.0
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "Return this OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI v3 specification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}