{
  "openapi": "3.1.0",
  "info": {
    "title": "Faro AI Visibility API",
    "description": "Scan any website for AI visibility. Returns a score out of 100, letter grade, and detailed check results across 7 categories with 47 individual checks.",
    "version": "1.0.0",
    "x-guidance": "Faro scores how ready a website is for AI agents. Paid (x402, USDC on Base): POST /agent/scan with JSON {\"url\": \"https://site.com\"} returns the full 0-100 audit with per-check results and fixes ($0.05). For one yes/no answer at $0.01, POST the same body to /agent/check/mcp (MCP or WebMCP tools), /agent/check/x402 (accepts agent payments) or /agent/check/pricing (machine-readable pricing). Free: GET /api/v1/registry searches scored businesses.",
    "contact": {
      "name": "Faro Support",
      "email": "hello@byfaro.ai",
      "url": "https://byfaro.ai/help"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://byfaro.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://byfaro.ai",
      "description": "Faro Production"
    }
  ],
  "paths": {
    "/api/audit": {
      "post": {
        "summary": "Scan a website for AI visibility (free)",
        "description": "Run a full AI visibility audit on any website. Checks 54 signals across 7 categories: Agent Permissions, Content Discoverability, Structured Data, Pricing Transparency, Agent Infrastructure, Agent Operability, and Trust & Identity. Returns a score (0-100) and prioritized fix list. Free, no payment required.",
        "operationId": "scanWebsite",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The website URL to audit",
                    "example": "https://example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful scan result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL provided"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/score-index": {
      "get": {
        "summary": "Get the Faro Score Index (free)",
        "description": "Returns the public leaderboard of AI visibility scores for well-known websites. Updated daily. Free, no payment required.",
        "operationId": "getScoreIndex",
        "security": [],
        "responses": {
          "200": {
            "description": "Score index entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "domain": { "type": "string" },
                      "score": { "type": "number" },
                      "grade": { "type": "string" },
                      "scannedAt": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/registry": {
      "get": {
        "summary": "Query the Faro Registry (free)",
        "description": "Businesses ranked by Faro AI visibility score, with agent capability flags. Same data as https://byfaro.ai/registry (HTML) and https://byfaro.ai/registry.md (Markdown). Free, no auth. 60 requests/minute per IP.",
        "operationId": "getRegistry",
        "security": [],
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search domain or business name" },
          { "name": "industry", "in": "query", "schema": { "type": "string" }, "description": "Exact industry name (case-insensitive)" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["score", "name", "industry", "recent"], "default": "score" } },
          { "name": "has", "in": "query", "schema": { "type": "string" }, "description": "Comma list of capabilities: llms-txt, api, mcp, pricing, schema, a2a, ai-crawlers, okf" },
          { "name": "min_score", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } },
          { "name": "has_api", "in": "query", "schema": { "type": "string", "enum": ["true"] } },
          { "name": "has_llms_txt", "in": "query", "schema": { "type": "string", "enum": ["true"] } },
          { "name": "has_mcp", "in": "query", "schema": { "type": "string", "enum": ["true"] } },
          { "name": "has_pricing", "in": "query", "schema": { "type": "string", "enum": ["true"] } },
          { "name": "allows_ai", "in": "query", "schema": { "type": "string", "enum": ["true"] } },
          { "name": "claimed", "in": "query", "schema": { "type": "string", "enum": ["true"] }, "description": "Verified-owner listings only" },
          { "name": "badge", "in": "query", "schema": { "type": "string", "enum": ["true"] }, "description": "Only sites showing the Faro badge" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "A page of registry entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer", "description": "Matching businesses across all pages" },
                        "registry_total": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "next": { "type": ["string", "null"] }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": { "type": "integer", "description": "Position in the full registry by score; ties share a rank" },
                          "domain": { "type": "string" },
                          "name": { "type": ["string", "null"] },
                          "industry": { "type": ["string", "null"] },
                          "score": { "type": "number" },
                          "grade": { "type": "string" },
                          "scanned_at": { "type": "string", "format": "date-time" },
                          "claimed": { "type": "boolean" },
                          "registry_url": { "type": "string" },
                          "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" } }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/scan/bulk": {
      "post": {
        "summary": "Scan multiple websites at once (free)",
        "description": "Bulk variant of /api/audit. Free, no payment required.",
        "operationId": "scanWebsitesBulk",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["urls"],
                "properties": {
                  "urls": {
                    "type": "array",
                    "items": { "type": "string", "format": "uri" },
                    "description": "Website URLs to audit"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful bulk scan result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ScanResult" }
                }
              }
            }
          },
          "400": { "description": "Invalid URLs provided" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/agent/scan": {
      "post": {
        "summary": "Full AI visibility audit (paid, x402)",
        "description": "Full AI visibility audit of any website: 54 checks across 7 categories (agent permissions, content discoverability, structured data, API/MCP infrastructure, pricing transparency, documentation, agent commerce). Returns 0-100 score, grade, per-check pass/fail and prioritized fixes. Use before recommending, buying from, or integrating with a site. Paid via the x402 protocol — USDC on Base mainnet, settled per-request. An unauthenticated request (any method) returns 402 with payment requirements.",
        "operationId": "agentScan",
        "security": [{ "x402Payment": [] }],
        "x-payment-info": {
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "USDC",
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" },
          "priceLabel": "$0.05",
          "protocols": [{ "x402": {} }],
          "payTo": "0x2586231a0ec268062f7ef79a290054cfd4c64aaa",
          "facilitator": "Coinbase CDP"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "example": "https://example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful audit result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScanResult" }
              }
            }
          },
          "402": {
            "description": "Payment required — response includes x402 payment requirements (accepted scheme, network, asset, amount, payTo). Returned for any method (GET/HEAD/POST) when no valid payment is present.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/X402PaymentRequired" }
              }
            }
          }
        }
      }
    },
    "/agent/check/mcp": {
      "post": {
        "summary": "Single-signal check: MCP/WebMCP exposure (paid, x402)",
        "description": "Does this website expose MCP / WebMCP tooling AI agents can call? Returns yes/no plus underlying checks and fixes. Paid via x402 — USDC on Base mainnet. An unauthenticated request (any method) returns 402 with payment requirements.",
        "operationId": "agentCheckMcp",
        "security": [{ "x402Payment": [] }],
        "x-payment-info": {
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "USDC",
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" },
          "priceLabel": "$0.01",
          "protocols": [{ "x402": {} }],
          "payTo": "0x2586231a0ec268062f7ef79a290054cfd4c64aaa",
          "facilitator": "Coinbase CDP"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "example": "https://example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResult" } } } },
          "402": {
            "description": "Payment required. Returned for any method (GET/HEAD/POST) when no valid payment is present.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } }
          }
        }
      }
    },
    "/agent/check/x402": {
      "post": {
        "summary": "Single-signal check: agent-payment readiness (paid, x402)",
        "description": "Can AI agents pay this website? Detects x402 support, /.well-known payment discovery and agent-commerce readiness. Paid via x402 — USDC on Base mainnet. An unauthenticated request (any method) returns 402 with payment requirements.",
        "operationId": "agentCheckX402",
        "security": [{ "x402Payment": [] }],
        "x-payment-info": {
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "USDC",
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" },
          "priceLabel": "$0.01",
          "protocols": [{ "x402": {} }],
          "payTo": "0x2586231a0ec268062f7ef79a290054cfd4c64aaa",
          "facilitator": "Coinbase CDP"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "example": "https://example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResult" } } } },
          "402": {
            "description": "Payment required. Returned for any method (GET/HEAD/POST) when no valid payment is present.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } }
          }
        }
      }
    },
    "/agent/check/pricing": {
      "post": {
        "summary": "Single-signal check: machine-readable pricing (paid, x402)",
        "description": "Is this website's pricing machine-readable for AI agents? Detects Offer schema with price/availability and pricing-transparency signals. Paid via x402 — USDC on Base mainnet. An unauthenticated request (any method) returns 402 with payment requirements.",
        "operationId": "agentCheckPricing",
        "security": [{ "x402Payment": [] }],
        "x-payment-info": {
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "USDC",
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" },
          "priceLabel": "$0.01",
          "protocols": [{ "x402": {} }],
          "payTo": "0x2586231a0ec268062f7ef79a290054cfd4c64aaa",
          "facilitator": "Coinbase CDP"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "example": "https://example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResult" } } } },
          "402": {
            "description": "Payment required. Returned for any method (GET/HEAD/POST) when no valid payment is present.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402Payment": {
        "type": "http",
        "scheme": "x402",
        "description": "Payment required via the x402 protocol (USDC on Base mainnet, settled through the Coinbase CDP facilitator). An unauthenticated request to a protected resource returns HTTP 402 with the required payment terms in the response body and Payment-Required header; the client resubmits with a signed payment payload to complete the request."
      }
    },
    "schemas": {
      "X402PaymentRequired": {
        "type": "object",
        "description": "Body of a 402 Payment Required response.",
        "properties": {
          "x402Version": { "type": "integer" },
          "error": { "type": "string" },
          "resource": {
            "type": "object",
            "properties": {
              "url": { "type": "string" },
              "description": { "type": "string" }
            }
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "eip155:8453" },
                "amount": { "type": "string", "description": "Price in atomic units of the asset" },
                "asset": { "type": "string", "description": "Token contract address (USDC on Base)" },
                "payTo": { "type": "string" },
                "maxTimeoutSeconds": { "type": "integer" }
              }
            }
          }
        }
      },
      "SignalResult": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "signal": { "type": "string" },
          "question": { "type": "string" },
          "answer": { "type": "boolean" },
          "checksPassed": { "type": "number" },
          "checksTotal": { "type": "number" },
          "checks": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Check" }
          }
        }
      },
      "ScanResult": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "AI visibility score out of 100"
          },
          "grade": {
            "type": "string",
            "enum": ["A", "B", "C", "D", "F"],
            "description": "Letter grade (A = 85-100, B = 70-84, C = 55-69, D = 40-54, F = 0-39)"
          },
          "categories": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CategoryResult" }
          },
          "scannedAt": { "type": "string", "format": "date-time" }
        }
      },
      "CategoryResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "score": { "type": "number" },
          "maxScore": { "type": "number" },
          "checks": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Check" }
          }
        }
      },
      "Check": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "passed": { "type": "boolean" },
          "impact": {
            "type": "string",
            "enum": ["high", "medium", "low"]
          },
          "detail": { "type": "string" },
          "fix": {
            "type": "string",
            "description": "Instructions for fixing a failed check. Null if check passed."
          }
        }
      }
    }
  }
}