{
  "openapi": "3.1.1",
  "info": {
    "title": "What Changed in This Law? API",
    "version": "1.0.0",
    "summary": "Compare two versions of a law or regulation section by section, with changed numbers and deadlines.",
    "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://whatchangedinthislaw.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Compare two versions of a law or regulation section by section, with changed numbers and deadlines.",
        "description": "Paste (or link) the old and new versions of a law, regulation, terms of service or policy. The text is split at §, Art. and Section headings, sections are aligned by their number, and every added, removed or modified section is shown with a word-level diff and the numbers, durations and obligation words (must/may/muss/kann…) that changed.\n\nMethodology:\n- Sections start at lines beginning with §, Art./Artikel/Article, Section/Sec. or Paragraph followed by a number; text before the first heading is the preamble.\n- Sections are aligned by their normalised number (LCS over section ids), so renumbered sections show as removed + added.\n- Inside a changed section a word-level LCS diff is computed; numbers, money amounts, percentages, durations and obligation words (must/shall/may, muss/kann/soll/darf…) present in only one version are listed.\n- Whitespace-only differences are ignored.\n\nNot legal advice. This is an automated, rule-based text analysis that can miss or misread clauses; it never claims completeness. For decisions with legal or financial consequences, ask a qualified professional (e.g. a lawyer, tax adviser or consumer advice centre). Always check the official consolidated text and the amending act for transitional provisions.",
        "tags": [
          "high-value"
        ],
        "x-mcp-tool": "what_changed_in_this_law",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhatChangedInThisLawInput"
              },
              "examples": {
                "example1": {
                  "summary": "Notice period shortened",
                  "value": {
                    "oldText": "§ 1 Scope\nThis act applies to consumer contracts.\n§ 2 Notice\nThe customer must give notice of termination at least 3 months before the end of the term.\n§ 3 Fees\nA processing fee of 25 EUR may be charged.",
                    "newText": "§ 1 Scope\nThis act applies to consumer contracts.\n§ 2 Notice\nThe customer may give notice of termination at any time with a notice period of 1 month.\n§ 3 Fees\nA processing fee of 25 EUR may be charged.\n§ 4 Online cancellation\nProviders must offer a cancellation button on their website.",
                    "citation": "Example amendment act",
                    "effectiveDate": "2026-12-01"
                  }
                },
                "example2": {
                  "summary": "German: Frist geändert",
                  "value": {
                    "oldText": "§ 5 Frist\nDer Antrag ist innerhalb von 14 Tagen zu stellen.\n§ 6 Gebühr\nDie Gebühr beträgt 50 Euro.",
                    "newText": "§ 5 Frist\nDer Antrag ist innerhalb von 30 Tagen zu stellen.\n§ 6 Gebühr\nDie Gebühr beträgt 50 Euro."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhatChangedInThisLawResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "WhatChangedInThisLawInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "oldText": {
            "title": "Old version (text)",
            "type": "string",
            "maxLength": 400000
          },
          "newText": {
            "title": "New version (text)",
            "type": "string",
            "maxLength": 400000
          },
          "oldUrl": {
            "title": "Or: URL of the old version",
            "description": "Official source (e.g. gesetze-im-internet.de, eur-lex.europa.eu, legislation.gov.uk).",
            "type": "string",
            "format": "uri"
          },
          "newUrl": {
            "title": "Or: URL of the new version",
            "type": "string",
            "format": "uri"
          },
          "citation": {
            "title": "Citation / amending act (optional)",
            "type": "string",
            "maxLength": 500
          },
          "effectiveDate": {
            "title": "Effective date of the new version (optional)",
            "type": "string",
            "format": "date"
          }
        },
        "required": []
      },
      "WhatChangedInThisLawResult": {
        "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": [
              "citation",
              "effectiveDate",
              "sectionsBefore",
              "sectionsAfter",
              "counts",
              "changes",
              "sources"
            ],
            "properties": {
              "citation": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "effectiveDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sectionsBefore": {
                "type": "integer"
              },
              "sectionsAfter": {
                "type": "integer"
              },
              "counts": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "added",
                  "removed",
                  "modified",
                  "headingOnly"
                ],
                "properties": {
                  "added": {
                    "type": "integer"
                  },
                  "removed": {
                    "type": "integer"
                  },
                  "modified": {
                    "type": "integer"
                  },
                  "headingOnly": {
                    "type": "integer"
                  }
                }
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "side",
                    "label",
                    "fetchedAt"
                  ],
                  "properties": {
                    "side": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "fetchedAt": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "changes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "section",
                    "heading",
                    "before",
                    "after",
                    "wordDiff",
                    "similarity",
                    "numbersChanged",
                    "durationsChanged",
                    "modalChanged"
                  ],
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "section-added",
                        "section-removed",
                        "section-modified",
                        "heading-changed"
                      ]
                    },
                    "section": {
                      "type": "string"
                    },
                    "heading": {
                      "type": "string"
                    },
                    "before": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "after": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "wordDiff": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "kept [-removed-] {+added+}"
                    },
                    "similarity": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "numbersChanged": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "removed",
                        "added"
                      ],
                      "properties": {
                        "removed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "added": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "durationsChanged": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "removed",
                        "added"
                      ],
                      "properties": {
                        "removed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "added": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "modalChanged": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "removed",
                        "added"
                      ],
                      "properties": {
                        "removed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "added": {
                          "type": "array",
                          "items": {
                            "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"
              }
            }
          }
        }
      }
    }
  }
}