{
  "openapi": "3.1.1",
  "info": {
    "title": "UnitProof Unit Calculator API",
    "version": "1.0.0",
    "summary": "Unit maths you can audit: dimension check, exact factors and a full derivation tree.",
    "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://unitproof.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Unit maths you can audit: dimension check, exact factors and a full derivation tree.",
        "description": "Type an expression such as \"3.5 km/h * 2 h to m\", \"72 F to C\" or \"1500 W * 3 h to kWh\". UnitProof parses it, checks dimensions over the SI base units, applies exact NIST/SI conversion factors and shows every step as a derivation tree, including correct absolute-vs-difference temperature handling.\n\nMethodology:\n- A tokenizer and recursive-descent parser read numbers (incl. scientific notation), units with SI prefixes (q…Q, incl. µ/u) and binary prefixes (Ki…Ei for bit/B), ^ powers (also ² ³ and \"m2\"), × ÷ + − and parentheses. Juxtaposition (\"2 h\", \"kg m\") binds tighter than explicit * and /, so \"60 km / 2 h\" = 30 km/h.\n- Every quantity is a value in coherent SI units plus a dimension vector over m, kg, s, A, K, mol, cd and bit; ISO 4217 currency codes are carried as opaque dimensions (never converted). The table has 144 named units.\n- Multiplication adds dimension exponents, division subtracts them, powers scale them; addition, subtraction and conversion require identical dimensions, otherwise the calculation stops with an explanation of the mismatch.\n- Temperatures: \"72 F\" or \"-40 C\" (a number directly followed by °C/°F) is an absolute temperature converted with its offset; absolute − absolute gives a difference; absolute ± difference stays absolute; multiplying, dividing or powering °C/°F is refused as ambiguous (use K or deltaC/deltaF). Converting a difference to °C/°F applies only the scale factor.\n- Exact factors follow the SI Brochure (9th ed.) and NIST SP 811 Appendix B (international foot/pound, US liquid gallon = 231 in³, Btu_IT, thermochemical calorie, etc.); conventional or measured values (mmHg, inHg, dalton) are flagged as not exact.\n- The derivation graph lists literals, unit definitions (with factor), operations and the final conversion; values are IEEE-754 doubles, shown unrounded and rounded to the requested significant digits.",
        "tags": [
          "developer"
        ],
        "x-mcp-tool": "unitproof",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnitproofInput"
              },
              "examples": {
                "example1": {
                  "summary": "Distance: 3.5 km/h for 2 h in metres",
                  "value": {
                    "expression": "3.5 km/h * 2 h to m"
                  }
                },
                "example2": {
                  "summary": "Temperature: 72 °F in °C",
                  "value": {
                    "expression": "72 F to C"
                  }
                },
                "example3": {
                  "summary": "Energy: 1500 W for 3 h in kWh",
                  "value": {
                    "expression": "1500 W * 3 h to kWh"
                  }
                },
                "example4": {
                  "summary": "Force: 75 kg at 9.81 m/s²",
                  "value": {
                    "expression": "9.81 m/s^2 * 75 kg to N"
                  }
                },
                "example5": {
                  "summary": "Mixed lengths: 1 mi + 200 m in km",
                  "value": {
                    "expression": "1 mi + 200 m to km",
                    "significantDigits": 4
                  }
                },
                "example6": {
                  "summary": "Opaque currency: 5 USD/kg × 2.5 kg",
                  "value": {
                    "expression": "5 USD/kg * 2.5 kg"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnitproofResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "UnitproofInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expression": {
            "title": "Expression",
            "description": "Numbers, units with SI prefixes, ^ powers, * / + − and parentheses; optional \"to\"/\"in\" target. Juxtaposition (e.g. \"2 h\") binds tighter than * and /. Bare C/F mean °C/°F.",
            "type": "string",
            "maxLength": 300
          },
          "significantDigits": {
            "title": "Significant digits (rounded value)",
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "default": 6
          }
        },
        "required": [
          "expression"
        ]
      },
      "UnitproofResult": {
        "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": [
              "expression",
              "value",
              "valueRounded",
              "significantDigits",
              "unit",
              "target",
              "valueSI",
              "unitSI",
              "dimension",
              "quantity",
              "dimensionCheck",
              "temperature",
              "alternatives",
              "derivation",
              "unitsUsed"
            ],
            "properties": {
              "expression": {
                "type": "string"
              },
              "value": {
                "type": "number",
                "description": "Unrounded IEEE-754 double result in the output unit."
              },
              "valueRounded": {
                "type": "number"
              },
              "significantDigits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 15
              },
              "unit": {
                "type": "string"
              },
              "target": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "valueSI": {
                "type": "number",
                "description": "Value in coherent SI units (kelvin for temperatures)."
              },
              "unitSI": {
                "type": "string"
              },
              "dimension": {
                "type": "string"
              },
              "quantity": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "dimensionCheck": {
                "type": "string",
                "enum": [
                  "ok"
                ]
              },
              "temperature": {
                "type": "string",
                "enum": [
                  "absolute",
                  "interval",
                  "none"
                ]
              },
              "alternatives": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "unit",
                    "value"
                  ],
                  "properties": {
                    "unit": {
                      "type": "string"
                    },
                    "value": {
                      "type": "number"
                    }
                  }
                }
              },
              "derivation": {
                "type": "array",
                "minItems": 2,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "kind",
                    "label",
                    "value",
                    "unit",
                    "dimension",
                    "children",
                    "note"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "literal",
                        "unit",
                        "operation",
                        "conversion",
                        "result"
                      ]
                    },
                    "label": {
                      "type": "string"
                    },
                    "value": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "unit": {
                      "type": "string"
                    },
                    "dimension": {
                      "type": "string"
                    },
                    "children": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              },
              "unitsUsed": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "symbol",
                    "name",
                    "definition",
                    "exact",
                    "source"
                  ],
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "definition": {
                      "type": "string"
                    },
                    "exact": {
                      "type": "boolean"
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "SI",
                        "NIST811",
                        "definition"
                      ]
                    }
                  }
                }
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}