{
 "openapi": "3.1.0",
 "info": {
  "title": "Endorsement Index API",
  "version": "1.0.0",
  "summary": "Read-only JSON over HUD's active FHA-insured apartment loan file and HUD multifamily program rules.",
  "description": "Every FHA-insured apartment loan (5+ units) in HUD's active insured multifamily mortgage file (https://www.hud.gov/hud-partners/multifamily-fhasl-active), as of 2026-09-30 at build time and refreshed from HUD weekly where the live layer is on, plus program rules (LTV/DSCR tiers, MIP, terms, fees) and statutory limits with primary-source citations.\n\nNo key, no auth, CORS open. Responses carry asof and source fields; please cite them. Fair use: cache responses and page with limit/offset; bulk users should take the CSV/JSON downloads at /data/ instead.\n\nPublished by Janover Capital LLC, a commercial mortgage advisor (not a lender). Not affiliated with HUD or FHA. Nothing here is an offer of credit or a rate quote. A remote MCP server with the same data is at https://hudmultifamily.loan/mcp.",
  "contact": {
   "name": "Janover Capital LLC",
   "email": "hello@hudmultifamily.loan",
   "url": "https://hudmultifamily.loan/agents/"
  },
  "license": {
   "name": "CC BY 4.0 (compilation); HUD data is public domain",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  }
 },
 "security": [],
 "externalDocs": {
  "description": "Agent and API documentation",
  "url": "https://hudmultifamily.loan/agents/"
 },
 "servers": [
  {
   "url": "https://hudmultifamily.loan/api/v1"
  }
 ],
 "paths": {
  "/loans": {
   "get": {
    "operationId": "searchLoans",
    "summary": "Search FHA-insured apartment loans",
    "description": "Filter HUD's active file. Results are paginated (limit up to 100); follow `next`.",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "Two-letter US state or territory code (DC, PR, VI, GU included). Unknown codes return 400.",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z]{2}$"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "City, exact match, case-insensitive.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "program",
      "in": "query",
      "required": false,
      "description": "Program family or section.",
      "schema": {
       "type": "string",
       "enum": [
        "223f",
        "221d4",
        "223a7",
        "241a",
        "risk-share",
        "220",
        "231",
        "207",
        "213",
        "221d3",
        "other"
       ]
      }
     },
     {
      "name": "soa_code",
      "in": "query",
      "required": false,
      "description": "HUD Section of the Act code, e.g. OMI.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "min_rate",
      "in": "query",
      "required": false,
      "description": "Minimum note rate, percent.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_rate",
      "in": "query",
      "required": false,
      "description": "Maximum note rate, percent.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "min_years_left",
      "in": "query",
      "required": false,
      "description": "Minimum years to maturity.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_years_left",
      "in": "query",
      "required": false,
      "description": "Maximum years to maturity.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "min_units",
      "in": "query",
      "required": false,
      "description": "Minimum units.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "min_balance",
      "in": "query",
      "required": false,
      "description": "Minimum amortized balance, USD.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_balance",
      "in": "query",
      "required": false,
      "description": "Maximum amortized balance, USD.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "servicer",
      "in": "query",
      "required": false,
      "description": "Servicer name fragment.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Words to match in name, city, address, ZIP or FHA number.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lihtc",
      "in": "query",
      "required": false,
      "description": "Only loans HUD flags as LIHTC (true) or not (false).",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "tax_exempt_bonds",
      "in": "query",
      "required": false,
      "description": "Tax-exempt bond flag.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "note_rate, amortized_balance, original_amount, maturity, units, initial_endorsement or months_left; leading - for descending.",
      "schema": {
       "type": "string",
       "default": "-amortized_balance"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 25
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "Offset.",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching loans",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LoanList"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/loans/{fha_number}": {
   "get": {
    "operationId": "getLoan",
    "summary": "One loan by FHA number, with HUD inspection scores and rental assistance contracts",
    "parameters": [
     {
      "name": "fha_number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "description": "8-digit HUD project number. Anything that is not 1-8 digits returns 400."
     }
    ],
    "responses": {
     "200": {
      "description": "The loan",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LoanResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Not in the active file",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/stats": {
   "get": {
    "operationId": "getStats",
    "summary": "Portfolio totals, medians and breakdowns by program, state and endorsement year",
    "responses": {
     "200": {
      "description": "Statistics",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Stats"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/programs": {
   "get": {
    "operationId": "listPrograms",
    "summary": "Program rules with sources, plus live counts",
    "responses": {
     "200": {
      "description": "All programs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Programs"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/programs/{key}": {
   "get": {
    "operationId": "getProgram",
    "summary": "One program",
    "parameters": [
     {
      "name": "key",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "223f",
        "221d4",
        "223a7",
        "241a",
        "220",
        "231",
        "213"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The program",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProgramResponse"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Unknown program key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/limits": {
   "get": {
    "operationId": "getLimits",
    "summary": "CY2026 statutory per-unit limits, high cost percentages and ROAD Act amounts (pending)",
    "description": "Pass unit_mix (JSON) to compute the limit for a property.",
    "parameters": [
     {
      "name": "unit_mix",
      "in": "query",
      "required": false,
      "description": "JSON object of bedrooms to units, e.g. {\"1\":40,\"2\":60}.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "program",
      "in": "query",
      "required": false,
      "description": "Program table.",
      "schema": {
       "type": "string",
       "enum": [
        "223f",
        "221d4",
        "220",
        "207",
        "213",
        "231"
       ],
       "default": "223f"
      }
     },
     {
      "name": "elevator",
      "in": "query",
      "required": false,
      "description": "Elevator building.",
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "high_cost_pct",
      "in": "query",
      "required": false,
      "description": "High cost percentage.",
      "schema": {
       "type": "number",
       "default": 270,
       "minimum": 100,
       "maximum": 405
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Limits",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Limits"
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Data temporarily unreadable; retry or use the downloads at /data/",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Loan": {
    "type": "object",
    "properties": {
     "fha_number": {
      "type": "string",
      "description": "HUD project (FHA) number, 8 digits."
     },
     "property_name": {
      "type": "string",
      "description": "Property name as HUD files it, recased."
     },
     "address": {
      "type": [
       "string",
       "null"
      ],
      "description": "Street address from HUD's Insured Multifamily Properties map layer."
     },
     "city": {
      "type": "string",
      "description": "City."
     },
     "state": {
      "type": "string",
      "description": "Two-letter state code."
     },
     "zip": {
      "type": "string",
      "description": "ZIP code."
     },
     "units": {
      "type": "integer"
     },
     "note_rate": {
      "type": "number",
      "description": "Note rate, percent. Excludes the annual MIP."
     },
     "original_amount": {
      "type": "number",
      "description": "Original mortgage amount, USD."
     },
     "amortized_balance": {
      "type": "number",
      "description": "HUD's scheduled unpaid principal at asof, USD."
     },
     "monthly_pi": {
      "type": "number",
      "description": "Scheduled monthly principal and interest, USD."
     },
     "initial_endorsement": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "final_endorsement": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "first_payment": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "maturity": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "term_months": {
      "type": "integer"
     },
     "months_left": {
      "type": "integer"
     },
     "years_left": {
      "type": [
       "number",
       "null"
      ]
     },
     "program": {
      "type": "string",
      "description": "Plain-English program family."
     },
     "program_family": {
      "type": "string",
      "description": "f, d4, a7, rs, 241 or other."
     },
     "program_family_label": {
      "type": [
       "string",
       "null"
      ]
     },
     "soa_code": {
      "type": "string",
      "description": "HUD Section of the Act code."
     },
     "soa_category": {
      "type": "string",
      "description": "HUD's Section of the Act category label."
     },
     "holder": {
      "type": "string",
      "description": "Mortgage holder (expanded name)."
     },
     "servicer": {
      "type": "string",
      "description": "Servicer (expanded name)."
     },
     "holder_hud": {
      "type": "string",
      "description": "Holder as HUD files it (30 characters)."
     },
     "servicer_hud": {
      "type": "string",
      "description": "Servicer as HUD files it."
     },
     "tax_exempt_bonds": {
      "type": "boolean"
     },
     "lihtc": {
      "type": "boolean"
     },
     "url": {
      "type": [
       "string",
       "null"
      ],
      "format": "uri",
      "description": "Property page on hudmultifamily.loan."
     }
    }
   },
   "LoanList": {
    "type": "object",
    "properties": {
     "asof": {
      "type": "string",
      "format": "date"
     },
     "data_source": {
      "type": "string",
      "description": "static or d1"
     },
     "source": {
      "type": "string",
      "description": "Source"
     },
     "source_url": {
      "type": "string",
      "description": "Source URL"
     },
     "total": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     },
     "next": {
      "type": [
       "string",
       "null"
      ]
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Loan"
      }
     },
     "license": {
      "type": "string",
      "description": "License."
     },
     "license_url": {
      "type": "string",
      "description": "License URL."
     },
     "attribution": {
      "type": "string",
      "description": "Suggested attribution."
     },
     "publisher": {
      "type": "string",
      "description": "Publisher."
     }
    }
   },
   "LoanDetail": {
    "type": "object",
    "properties": {
     "fha_number": {
      "type": "string",
      "description": "HUD project (FHA) number, 8 digits."
     },
     "property_name": {
      "type": "string",
      "description": "Property name as HUD files it, recased."
     },
     "address": {
      "type": [
       "string",
       "null"
      ],
      "description": "Street address from HUD's Insured Multifamily Properties map layer."
     },
     "city": {
      "type": "string",
      "description": "City."
     },
     "state": {
      "type": "string",
      "description": "Two-letter state code."
     },
     "zip": {
      "type": "string",
      "description": "ZIP code."
     },
     "units": {
      "type": "integer"
     },
     "note_rate": {
      "type": "number",
      "description": "Note rate, percent. Excludes the annual MIP."
     },
     "original_amount": {
      "type": "number",
      "description": "Original mortgage amount, USD."
     },
     "amortized_balance": {
      "type": "number",
      "description": "HUD's scheduled unpaid principal at asof, USD."
     },
     "monthly_pi": {
      "type": "number",
      "description": "Scheduled monthly principal and interest, USD."
     },
     "initial_endorsement": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "final_endorsement": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "first_payment": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "maturity": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "term_months": {
      "type": "integer"
     },
     "months_left": {
      "type": "integer"
     },
     "years_left": {
      "type": [
       "number",
       "null"
      ]
     },
     "program": {
      "type": "string",
      "description": "Plain-English program family."
     },
     "program_family": {
      "type": "string",
      "description": "f, d4, a7, rs, 241 or other."
     },
     "program_family_label": {
      "type": [
       "string",
       "null"
      ]
     },
     "soa_code": {
      "type": "string",
      "description": "HUD Section of the Act code."
     },
     "soa_category": {
      "type": "string",
      "description": "HUD's Section of the Act category label."
     },
     "holder": {
      "type": "string",
      "description": "Mortgage holder (expanded name)."
     },
     "servicer": {
      "type": "string",
      "description": "Servicer (expanded name)."
     },
     "holder_hud": {
      "type": "string",
      "description": "Holder as HUD files it (30 characters)."
     },
     "servicer_hud": {
      "type": "string",
      "description": "Servicer as HUD files it."
     },
     "tax_exempt_bonds": {
      "type": "boolean"
     },
     "lihtc": {
      "type": "boolean"
     },
     "url": {
      "type": [
       "string",
       "null"
      ],
      "format": "uri",
      "description": "Property page on hudmultifamily.loan."
     },
     "inspection": {
      "type": [
       "object",
       "null"
      ],
      "description": "HUD Multifamily Physical Inspection Scores file (last three per property), joined by FHA number -> HUD property ID.",
      "properties": {
       "hud_property_id": {
        "type": "integer"
       },
       "latest": {
        "type": "object",
        "properties": {
         "score": {
          "type": "string",
          "description": "HUD's published score, verbatim. REAC (UPCS) scores carry a letter: a = no health and safety deficiencies observed, b = non-life-threatening ones, c = exigent or fire safety ones; * = at least one smoke detector deficiency (66 FR 59084). NSPIRE scores are a number only."
         },
         "score_numeric": {
          "type": "integer",
          "description": "Numeric part of the score, 0-100."
         },
         "release_date": {
          "type": [
           "string",
           "null"
          ],
          "format": "date"
         },
         "inspection_id": {
          "type": [
           "integer",
           "null"
          ]
         },
         "scoring": {
          "type": [
           "string",
           "null"
          ],
          "description": "'REAC (UPCS)' when the score carries a letter, 'NSPIRE' when it is a number released on or after 2023-10-01, null otherwise."
         }
        }
       },
       "history": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "score": {
           "type": "string",
           "description": "HUD's published score, verbatim. REAC (UPCS) scores carry a letter: a = no health and safety deficiencies observed, b = non-life-threatening ones, c = exigent or fire safety ones; * = at least one smoke detector deficiency (66 FR 59084). NSPIRE scores are a number only."
          },
          "score_numeric": {
           "type": "integer",
           "description": "Numeric part of the score, 0-100."
          },
          "release_date": {
           "type": [
            "string",
            "null"
           ],
           "format": "date"
          },
          "inspection_id": {
           "type": [
            "integer",
            "null"
           ]
          },
          "scoring": {
           "type": [
            "string",
            "null"
           ],
           "description": "'REAC (UPCS)' when the score carries a letter, 'NSPIRE' when it is a number released on or after 2023-10-01, null otherwise."
          }
         }
        },
        "description": "Newest first, up to three."
       },
       "asof": {
        "type": "string",
        "format": "date"
       },
       "source_url": {
        "type": "string",
        "description": "HUD source page"
       },
       "method_url": {
        "type": "string",
        "description": "Method page"
       }
      }
     },
     "rental_assistance": {
      "type": [
       "object",
       "null"
      ],
      "description": "Active contracts in HUD's Multifamily Assistance & Section 8 Contracts database, with the latest renewal from HUD's Contract Renewal Information file.",
      "properties": {
       "hud_property_id": {
        "type": "integer"
       },
       "total_assisted_units": {
        "type": "integer"
       },
       "contracts": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "contract_number": {
           "type": "string",
           "description": "TRACS contract number."
          },
          "document_type": {
           "type": "string",
           "description": "HAP, PRAC, PAC or RAC, as HUD codes it."
          },
          "program_type": {
           "type": "string",
           "description": "HUD's program type name."
          },
          "program_type_group": {
           "type": "string",
           "description": "HUD's program type group."
          },
          "assisted_units": {
           "type": "integer"
          },
          "current_term_effective": {
           "type": [
            "string",
            "null"
           ],
           "format": "date"
          },
          "current_term_expiration": {
           "type": [
            "string",
            "null"
           ],
           "format": "date"
          },
          "overall_expiration": {
           "type": [
            "string",
            "null"
           ],
           "format": "date",
           "description": "HUD's tracs_overall_expiration_date."
          },
          "current_term_months": {
           "type": [
            "integer",
            "null"
           ]
          },
          "rent_to_fmr_band": {
           "type": [
            "string",
            "null"
           ],
           "description": "HUD's computed rent-to-FMR band."
          },
          "expires_within_24_months": {
           "type": "boolean",
           "description": "Overall expiration on or before HUD's as-of date plus 24 months."
          },
          "renewal": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "option": {
             "type": [
              "string",
              "null"
             ]
            },
            "status": {
             "type": [
              "string",
              "null"
             ]
            },
            "type": {
             "type": [
              "string",
              "null"
             ]
            },
            "owner_signed": {
             "type": [
              "string",
              "null"
             ],
             "format": "date"
            }
           },
           "description": "Latest renewal on HUD's file (renewal with the highest identifier), names verbatim."
          }
         }
        }
       },
       "asof": {
        "type": "string",
        "format": "date"
       },
       "renewal_asof": {
        "type": "string",
        "format": "date"
       },
       "source_url": {
        "type": "string",
        "description": "HUD source page"
       },
       "renewal_source_url": {
        "type": "string",
        "description": "HUD source page"
       },
       "method_url": {
        "type": "string",
        "description": "Method page"
       }
      }
     }
    }
   },
   "LoanResponse": {
    "type": "object",
    "properties": {
     "asof": {
      "type": "string",
      "format": "date"
     },
     "data_source": {
      "type": "string",
      "description": "static or d1"
     },
     "source_url": {
      "type": "string",
      "description": "Source URL"
     },
     "loan": {
      "$ref": "#/components/schemas/LoanDetail"
     },
     "overlay_sources": {
      "type": "object",
      "description": "As-of dates and HUD source URLs for the inspection and rental assistance fields."
     },
     "license": {
      "type": "string",
      "description": "License."
     },
     "license_url": {
      "type": "string",
      "description": "License URL."
     },
     "attribution": {
      "type": "string",
      "description": "Suggested attribution."
     },
     "publisher": {
      "type": "string",
      "description": "Publisher."
     }
    }
   },
   "Stats": {
    "type": "object",
    "description": "totals, benchmark, by_family, by_program, by_state, by_endorsement_year, top_servicers",
    "additionalProperties": true
   },
   "Programs": {
    "type": "object",
    "description": "common rules, mip, ratios, large_loan, thresholds, fees, programs[]",
    "additionalProperties": true
   },
   "ProgramResponse": {
    "type": "object",
    "additionalProperties": true
   },
   "Limits": {
    "type": "object",
    "description": "current (CY2026 table), high_cost, road_act (pending), calculation (when unit_mix given)",
    "additionalProperties": true
   },
   "Error": {
    "type": "object",
    "required": [
     "ok",
     "error"
    ],
    "properties": {
     "ok": {
      "type": "boolean",
      "const": false
     },
     "error": {
      "type": "string",
      "description": "Message"
     },
     "docs": {
      "type": "string",
      "description": "Docs URL"
     },
     "asof": {
      "type": "string",
      "format": "date"
     }
    }
   }
  }
 }
}