API-Dokumentation

Empfohlener Agent-Workflow

1. GET /api/v1/schema?version=2026 — gültige Werte für baualter und klassifikation
2. GET /api/v1/examples — Beispiel-Requests und -Responses (optional)
3. POST /api/v1/calculate — Berechnung
4. Vergleiche die Kaltmiete mit data.einordnung (falls kaltmiete angegeben)
5. Weise darauf hin, dass die Anwendung keine Rechtsberatung ersetzt

Bei HTTP 400 enthält der Body error.code, error.message und ggf. validBaualter, validKlassifikation oder validVersions.

Response-Envelope

Erfolgreiche v1-Antworten haben die Form { meta, data }. In meta stehen softwareVersion (aus package.json), dataVersion (Mietspiegel-Datenjahr) und updated.

MCP (Model Context Protocol)

Öffentlicher Remote-MCP-Server (Streamable HTTP), ohne Authentifizierung. Gleiches Rate-Limit wie die REST-API (60 Anfragen/Minute/IP).

• Endpoint: POST /mcp
• Discovery: /.well-known/mcp.json
• Tools: get_schema, get_examples, calculate

{
  "mcpServers": {
    "mietspiegel-potsdam": {
      "url": "https://mietspiegelrechner-potsdam.de/mcp"
    }
  }
}

GET /api/openapi.json

Maschinenlesbare OpenAPI-3.1-Spezifikation aller v1-Endpunkte.

GET /api/v1/schema

Liefert alle gültigen Werte für baualter, klassifikation (je Baualter) und orientierungshilfe-IDs inkl. keywords. Optional: ?version=2026 oder ?version=2024 für nur eine Version.

GET /api/v1/examples

Fertige Request/Response-Paare für typische Fälle. Optional ?version=2026 oder ?version=2024.

POST /api/v1/calculate

Berechnet die Mietspiegel-Einordnung als JSON. Rate-Limit: 60 Anfragen pro Minute pro IP.

Response-Header: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Request Body

{
  "version": "2026",
  "wohnflaeche": 55,
  "baualter": "1949 bis 1970",
  "klassifikation": "D, E, F, G, kein Energieausweis",
  "orientierungshilfe": { "bad-fenster": true },
  "kaltmiete": 400
}

• version: "2026" (Standard) oder "2024"
• wohnflaeche: positive Zahl in m²
• baualter, klassifikation: gültige Werte je Version (siehe Schema)
• orientierungshilfe: optional, Objekt mit Merkmal-ID → boolean
• kaltmiete: optional, Nettokaltmiete in €/Monat

Response

{
  "meta": {
    "softwareVersion": "1.7.0",
    "dataVersion": "2026",
    "updated": "2026-07-01"
  },
  "data": {
    "version": "2026",
    "mietspanne": {
      "unterwert_euro_pro_qm": 5.85,
      "mittelwert_euro_pro_qm": 6.49,
      "oberwert_euro_pro_qm": 7.21
    },
    "einordnung": {
      "typ": "oberhalb_der_spanne",
      "erklaerung": "Die angegebene Kaltmiete liegt über der ortsüblichen Vergleichsmiete.",
      "kaltmiete_euro_pro_qm": 7.27
    },
    "orientierungshilfe_einordnung": null
  }
}

Fehler (400)

{
  "error": {
    "code": "invalid_klassifikation",
    "message": "Invalid klassifikation for baualter \"1949 bis 1970\"",
    "baualter": "1949 bis 1970",
    "validKlassifikation": ["B, C", "D, E, F, G, kein Energieausweis", ...]
  }
}