{
  "openapi": "3.1.0",
  "info": {
    "title": "BestBusinessLoans Data API",
    "summary": "Read-only public data on reviewed UK business loan lenders and rates.",
    "description": "Machine-readable access to the BestBusinessLoans UK Business Loan Lender Index: reviewed lender terms (ticket range, typical rate, decision time, soft search, Ltd-only, FCA-regulated) and a current market snapshot. Source of truth is the on-site Lender Index Dataset. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-05-26",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "BestBusinessLoans",
      "url": "https://bestbusinessloans.ai/data/api/"
    }
  },
  "servers": [
    { "url": "https://bestbusinessloans.ai", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://bestbusinessloans.ai/data/api/"
  },
  "paths": {
    "/api/lenders": {
      "get": {
        "operationId": "listLenders",
        "summary": "List reviewed UK business loan lenders",
        "description": "Returns all reviewed lenders, or a filtered subset when query params are supplied.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on lender name, summary and best-for tags.",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by derived product category.",
            "schema": {
              "type": "string",
              "enum": ["term-loan", "flexi-loan", "merchant-cash-advance", "asset-finance", "invoice-finance", "commercial-mortgage", "bridging", "development-finance", "business-banking", "broker", "other"]
            }
          },
          {
            "name": "fca",
            "in": "query",
            "required": false,
            "description": "Set to true to return only FCA-regulated lenders.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "soft_search",
            "in": "query",
            "required": false,
            "description": "Set to true to return only lenders that quote on a soft search.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "ltd_only",
            "in": "query",
            "required": false,
            "description": "Set to true to return only lenders that lend to limited companies only.",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of lenders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "count": { "type": "integer" },
                    "lenders": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Lender" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/lenders/{slug}": {
      "get": {
        "operationId": "getLender",
        "summary": "Get a single lender by slug",
        "description": "Accepts the canonical lender slug (e.g. funding-circle).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "funding-circle"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching lender.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "lender": { "$ref": "#/components/schemas/Lender" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No lender matches the slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/rates": {
      "get": {
        "operationId": "getRates",
        "summary": "Current UK business loan market snapshot",
        "description": "Lender count, FCA-regulated count, category breakdown across reviewed lenders, plus the Bank of England base rate as a dated reference.",
        "responses": {
          "200": {
            "description": "Market snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RatesSnapshot" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Lender": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "legal_name": { "type": "string" },
          "company_number": { "type": "string" },
          "founded_year": { "type": "integer" },
          "homepage": { "type": "string", "format": "uri" },
          "profile_url": { "type": "string", "format": "uri" },
          "product_type": { "type": "string" },
          "category": {
            "type": "string",
            "enum": ["term-loan", "flexi-loan", "merchant-cash-advance", "asset-finance", "invoice-finance", "commercial-mortgage", "bridging", "development-finance", "business-banking", "broker", "other"]
          },
          "ticket_range": { "type": "string" },
          "typical_rate": { "type": "string" },
          "decision_time": { "type": "string" },
          "soft_search_only": { "type": "boolean" },
          "ltd_only": { "type": "boolean" },
          "fca_regulated": { "type": "boolean" },
          "rating": {
            "type": "object",
            "properties": {
              "overall": { "type": "number" },
              "transparency": { "type": "number" },
              "eligibility": { "type": "number" },
              "speed": { "type": "number" },
              "decline_handling": { "type": "number" }
            }
          },
          "summary": { "type": "string" },
          "pros": { "type": "array", "items": { "type": "string" } },
          "cons": { "type": "array", "items": { "type": "string" } },
          "best_for": { "type": "array", "items": { "type": "string" } },
          "weak_at": { "type": "array", "items": { "type": "string" } },
          "last_reviewed": { "type": "string", "format": "date" },
          "companies_house": {
            "type": "object",
            "properties": {
              "company_number": { "type": "string" },
              "source": { "type": "string", "format": "uri" }
            }
          }
        },
        "required": ["slug", "name", "homepage", "product_type", "category"]
      },
      "RatesSnapshot": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "as_of": { "type": "string", "format": "date" },
          "currency": { "type": "string" },
          "region": { "type": "string" },
          "bank_of_england_base_rate": {
            "type": "object",
            "properties": {
              "value": { "type": "number" },
              "unit": { "type": "string" },
              "effective_date": { "type": "string", "format": "date" },
              "as_of": { "type": "string", "format": "date" },
              "source": { "type": "string", "format": "uri" },
              "note": { "type": "string" }
            }
          },
          "lenders_count": { "type": "integer" },
          "fca_regulated_count": { "type": "integer" },
          "soft_search_count": { "type": "integer" },
          "lenders_by_category": { "type": "object", "additionalProperties": { "type": "integer" } },
          "note": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}