{
  "openapi": "3.1.1",
  "info": {
    "title": "AR Sales Agent Public Tools API",
    "version": "1.0.0",
    "description": "Three existing, quota-limited public tools. This API does not provide access to private accounts, saved leads, CRM data, or automatic outreach. Results are point-in-time research signals."
  },
  "servers": [{ "url": "https://arsalesagent.com" }],
  "paths": {
    "/api/public-tools/lead-finder": {
      "post": {
        "operationId": "searchLocalBusinessListings",
        "summary": "Preview local business listings",
        "description": "Search Google Maps by category and location. Returns at most five results. The optional no-website filter checks up to 40 returned listings; a missing listing link does not prove that no website exists. Subject to a daily per-IP and shared usage budget.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSearchInput" } } } },
        "responses": {
          "200": { "description": "A limited listing preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSearchResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public-tools/email-verifier": {
      "post": {
        "operationId": "checkPublicEmailAddress",
        "summary": "Check an email address",
        "description": "Checks syntax, DNS, and MX records. A mailbox provider assessment is returned only when configured and available; it does not guarantee delivery. Subject to daily usage limits.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckInput" } } } },
        "responses": {
          "200": { "description": "Available email checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public-tools/website-audit": {
      "post": {
        "operationId": "auditPublicWebsiteHtml",
        "summary": "Audit a public page's initial HTML",
        "description": "Fetches a public HTTP or HTTPS URL and reports seven observable HTML checks. The score is the percentage passed; it is not a speed or complete accessibility measurement. Private and local network addresses are blocked. Subject to daily usage limits.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteAuditInput" } } } },
        "responses": {
          "200": { "description": "Seven HTML checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteAuditResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "422": { "$ref": "#/components/responses/UpstreamError" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" },
          "503": { "$ref": "#/components/responses/Unavailable" },
          "504": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LeadSearchInput": { "type": "object", "required": ["category", "location"], "properties": { "category": { "type": "string", "minLength": 2, "maxLength": 70 }, "location": { "type": "string", "minLength": 2, "maxLength": 100 }, "withoutWebsite": { "type": "boolean", "default": false } } },
      "EmailCheckInput": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } } },
      "WebsiteAuditInput": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } } },
      "LeadSearchResult": { "type": "object", "required": ["places", "scanned", "filteredOut", "scope", "hasMore", "attribution", "note"], "properties": { "places": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": ["name", "address", "website", "mapsUrl"], "properties": { "name": { "type": "string" }, "address": { "type": ["string", "null"] }, "website": { "type": ["string", "null"] }, "mapsUrl": { "type": ["string", "null"] } } } }, "scanned": { "type": "integer" }, "filteredOut": { "type": "boolean" }, "scope": { "type": "string" }, "hasMore": { "type": "boolean" }, "attribution": { "type": "string", "const": "Google Maps" }, "note": { "type": ["string", "null"] } } },
      "EmailCheckResult": { "type": "object", "required": ["format", "domain", "mx", "mailbox", "note"], "properties": { "format": { "type": "string", "const": "valid" }, "domain": { "type": "object", "required": ["name", "status"], "properties": { "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/DnsStatus" } } }, "mx": { "type": "object", "required": ["status", "records"], "properties": { "status": { "$ref": "#/components/schemas/DnsStatus" }, "records": { "type": "array", "items": { "type": "object", "required": ["host", "priority"], "properties": { "host": { "type": "string" }, "priority": { "type": "integer" } } } } } }, "mailbox": { "type": "object", "required": ["status", "source"], "properties": { "status": { "type": "string", "enum": ["not_checked", "unavailable", "deliverable", "risky", "undeliverable", "unknown"] }, "source": { "type": ["string", "null"] } } }, "note": { "type": "string" } } },
      "DnsStatus": { "type": "string", "enum": ["found", "not_found", "unavailable"] },
      "WebsiteAuditResult": { "type": "object", "required": ["url", "title", "description", "complete", "score", "checks", "note"], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "complete": { "type": "boolean" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "checks": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "type": "object", "required": ["label", "pass", "advice"], "properties": { "label": { "type": "string" }, "pass": { "type": "boolean" }, "advice": { "type": "string" } } } }, "note": { "type": "string" } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooLarge": { "description": "Request body exceeds 4096 characters or its declared length exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Per-IP or shared public usage limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "UpstreamError": { "description": "Provider request or website fetch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unavailable": { "description": "Tool or quota counter unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}