{
  "openapi": "3.1.1",
  "info": {
    "title": "Mashkantes Mortgage Payment API",
    "version": "1.0.0",
    "description": "Calculate fixed-rate, unlinked annuity scenarios in ILS. No authentication, contact details or documents. Accepts numeric scenarios only. Does not create a lead or change an account. Not a bank quote, lending approval or personalized recommendation. It does not support inflation linkage, future rate changes, fees, insurance, grace or balloon payments."
  },
  "servers": [
    {
      "url": "https://mashkantes.co.il"
    }
  ],
  "externalDocs": {
    "description": "Hebrew usage guide, formula, worked example and privacy limits",
    "url": "https://mashkantes.co.il/tools/api/"
  },
  "security": [],
  "paths": {
    "/api/v1/mortgage-payment": {
      "post": {
        "operationId": "calculateMortgagePayment",
        "summary": "Calculate monthly payments and total interest for fixed-rate unlinked loan scenarios",
        "description": "Send 1 to 20 tracks in a JSON body of at most 4096 bytes. Only principal, annual_rate_percent and term_months are accepted per track. Do not send names, phone numbers, document contents, account identifiers or any extra fields. Each track holds its supplied rate constant. Results include assumptions and a source link. Netlify is configured to allow 60 requests per 60 seconds per IP and domain; enforcement may lag. No application database storage or AI provider calls. Infrastructure may process ordinary request logs under the privacy policy.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculationRequest"
              },
              "example": {
                "tracks": [
                  {
                    "principal": 1000000,
                    "annual_rate_percent": 5,
                    "term_months": 300
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculated scenario, rounded to two decimal places. Aggregate totals use unrounded payments.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculationResult"
                },
                "example": {
                  "version": "1.0.0",
                  "calculation": "fixed_rate_unlinked_annuity",
                  "currency": "ILS",
                  "tracks": [
                    {
                      "principal": 1000000,
                      "annual_rate_percent": 5,
                      "term_months": 300,
                      "monthly_payment": 5845.9,
                      "total_payment": 1753770.12,
                      "total_interest": 753770.12
                    }
                  ],
                  "totals": {
                    "principal": 1000000,
                    "initial_monthly_payment": 5845.9,
                    "term_months": 300,
                    "total_payment": 1753770.12,
                    "total_interest": 753770.12
                  },
                  "assumptions": [
                    "Fixed nominal annual interest, divided by 12, with monthly payments at the end of each month.",
                    "No inflation or currency linkage, interest-rate changes, grace periods or balloon payments.",
                    "Excludes insurance, fees, taxes and early-repayment charges.",
                    "Totals use unrounded payments; displayed amounts are rounded to two decimal places.",
                    "A mathematical estimate, not a bank offer, lending approval or personal recommendation."
                  ],
                  "source": {
                    "name": "Mashkantes mortgage calculator",
                    "url": "https://mashkantes.co.il/calculator/",
                    "documentation": "https://mashkantes.co.il/tools/api/"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, query string or input values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. Use POST or OPTIONS.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 4096 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type must be application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hosting rate limit reached. Wait before retrying. The hosting platform may return a non-JSON response."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CalculationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tracks"
        ],
        "properties": {
          "tracks": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/TrackInput"
            }
          }
        }
      },
      "TrackInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "principal",
          "annual_rate_percent",
          "term_months"
        ],
        "properties": {
          "principal": {
            "type": "number",
            "minimum": 1,
            "maximum": 50000000,
            "description": "Loan principal in ILS."
          },
          "annual_rate_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "description": "Nominal annual rate in percent. 5 means 5%, not 0.05. This is a user-supplied scenario, not a quoted market rate."
          },
          "term_months": {
            "type": "integer",
            "minimum": 1,
            "maximum": 360,
            "description": "Number of monthly payments, in months, not years."
          }
        }
      },
      "TrackResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "principal",
          "annual_rate_percent",
          "term_months",
          "monthly_payment",
          "total_payment",
          "total_interest"
        ],
        "properties": {
          "principal": {
            "type": "number",
            "minimum": 1,
            "maximum": 50000000,
            "description": "Loan principal in ILS."
          },
          "annual_rate_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "description": "Nominal annual rate in percent. 5 means 5%, not 0.05. This is a user-supplied scenario, not a quoted market rate."
          },
          "term_months": {
            "type": "integer",
            "minimum": 1,
            "maximum": 360,
            "description": "Number of monthly payments, in months, not years."
          },
          "monthly_payment": {
            "type": "number",
            "minimum": 0,
            "description": "ILS, rounded to two decimal places."
          },
          "total_payment": {
            "type": "number",
            "minimum": 0,
            "description": "ILS, rounded to two decimal places."
          },
          "total_interest": {
            "type": "number",
            "minimum": 0,
            "description": "ILS, rounded to two decimal places."
          }
        }
      },
      "CalculationResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "calculation",
          "currency",
          "tracks",
          "totals",
          "assumptions",
          "source"
        ],
        "properties": {
          "version": {
            "type": "string",
            "const": "1.0.0"
          },
          "calculation": {
            "type": "string",
            "const": "fixed_rate_unlinked_annuity"
          },
          "currency": {
            "type": "string",
            "const": "ILS"
          },
          "tracks": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/TrackResult"
            }
          },
          "totals": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "principal",
              "initial_monthly_payment",
              "term_months",
              "total_payment",
              "total_interest"
            ],
            "properties": {
              "principal": {
                "type": "number",
                "minimum": 0,
                "description": "ILS, rounded to two decimal places."
              },
              "initial_monthly_payment": {
                "type": "number",
                "minimum": 0,
                "description": "Sum of initial monthly payments. It decreases as shorter tracks finish."
              },
              "term_months": {
                "type": "integer",
                "minimum": 1,
                "maximum": 360,
                "description": "Longest track duration."
              },
              "total_payment": {
                "type": "number",
                "minimum": 0,
                "description": "ILS, rounded to two decimal places."
              },
              "total_interest": {
                "type": "number",
                "minimum": 0,
                "description": "ILS, rounded to two decimal places."
              }
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "url",
              "documentation"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "documentation": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "error",
          "documentation"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}