{
  "openapi": "3.1.0",
  "info": {
    "title": "FindBusiness AI Readiness Assessment API",
    "description": "Assess a business website's visibility to AI assistants. Returns an A-F grade from 17 automated checks across three pillars: Discoverability (20%): agent_interface, crawl_health, link_health, llms_txt, page_speed, ssl, url_structure; Clarity (45%): content_structure, identity_clarity, location_clarity, service_clarity, structured_data; Trust (35%): accessibility, contact_accessible, entity_consistency, google_presence, legal_compliance. This endpoint is not a public API. It is a Firebase callable protected by App Check attestation, so requests from outside the FindBusiness web app are rejected. The assessment itself is free and requires no account — run one at https://findbusiness.ai.",
    "version": "1.1.0",
    "contact": {
      "name": "Dependable AI Solutions",
      "email": "admin@dependableaisolutions.com",
      "url": "https://dependableaisolutions.com"
    },
    "license": {
      "name": "Terms of Service",
      "url": "https://findbusiness.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://us-central1-businessregistry-e25d4.cloudfunctions.net",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "appCheck": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Firebase-AppCheck",
        "description": "This endpoint is not a public API. It is a Firebase callable protected by App Check attestation, so requests from outside the FindBusiness web app are rejected. The assessment itself is free and requires no account — run one at https://findbusiness.ai."
      }
    }
  },
  "security": [
    {
      "appCheck": []
    }
  ],
  "paths": {
    "/assessUrl": {
      "post": {
        "operationId": "assessUrl",
        "summary": "Run an AI readiness assessment on a business website",
        "description": "Fetches the target URL, runs 17 automated checks (accessibility, agent_interface, contact_accessible, content_structure, crawl_health, entity_consistency, google_presence, identity_clarity, legal_compliance, link_health, llms_txt, location_clarity, page_speed, service_clarity, ssl, structured_data, url_structure), scores them across three pillars, and returns an A-F grade with a prioritized action plan. Results are cached for 24 hours unless forceRefresh is set. Every report is public at its own URL. This endpoint is not a public API. It is a Firebase callable protected by App Check attestation, so requests from outside the FindBusiness web app are rejected. The assessment itself is free and requires no account — run one at https://findbusiness.ai.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "object",
                    "required": [
                      "url"
                    ],
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "The business website URL to assess",
                        "example": "https://example.com"
                      },
                      "forceRefresh": {
                        "type": "boolean",
                        "description": "Bypass the 24-hour cache and re-scan now"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assessment result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Assessment document ID"
                        },
                        "siteId": {
                          "type": "string",
                          "description": "Normalized site identifier"
                        },
                        "url": {
                          "type": "string"
                        },
                        "overallScore": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "overallGrade": {
                          "type": "string",
                          "enum": [
                            "A",
                            "B",
                            "C",
                            "D",
                            "F"
                          ]
                        },
                        "pillars": {
                          "type": "object",
                          "description": "Scores per pillar, keyed by id: findability (shown as \"Discoverability\", 20%), clarity (shown as \"Clarity\", 45%), trust (shown as \"Trust\", 35%)"
                        },
                        "checks": {
                          "type": "array",
                          "description": "The 17 individual check results"
                        },
                        "actionPlan": {
                          "type": "array",
                          "description": "Prioritized fixes, up to five. Filtered to checks with measured impact and real headroom, so a strong site can legitimately receive fewer."
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "failCount": {
                              "type": "integer"
                            },
                            "warnCount": {
                              "type": "integer"
                            },
                            "passCount": {
                              "type": "integer"
                            },
                            "totalChecks": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "App Check attestation missing or invalid"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    }
  }
}