{
  "openapi": "3.0.3",
  "info": {
    "title": "AgentBoard API",
    "version": "2.0.0",
    "description": "Public agent-readiness scoreboard. Rank is the score, not a bid.",
    "contact": { "email": "help@brittongarrett.com", "url": "https://agentboardai.app/agents" }
  },
  "servers": [{ "url": "https://agentboardai.app" }],
  "paths": {
    "/api/board": {
      "get": {
        "summary": "Ranked scoreboard",
        "operationId": "getBoard",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": { "type": "string", "enum": ["score", "recent"] }
          },
          { "name": "min_score", "in": "query", "schema": { "type": "number" } },
          { "name": "verified", "in": "query", "schema": { "type": "string" } },
          { "name": "has_mcp", "in": "query", "schema": { "type": "string" } },
          { "name": "has_openapi", "in": "query", "schema": { "type": "string" } },
          { "name": "has_pricing", "in": "query", "schema": { "type": "string" } },
          { "name": "q", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Board payload" } }
      }
    },
    "/api/site/{host}": {
      "get": {
        "summary": "Site grade",
        "operationId": "getSite",
        "parameters": [
          {
            "name": "host",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": { "200": { "description": "Site and last scan" }, "404": { "description": "Not scanned" } }
      }
    },
    "/api/scan": {
      "post": {
        "summary": "Scan a URL",
        "operationId": "scanUrl",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string" },
                  "category": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Scan result" } }
      }
    },
    "/api/buy": {
      "post": {
        "summary": "Create checkout for recrawl or featured",
        "operationId": "buyProduct",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url", "product"],
                "properties": {
                  "url": { "type": "string" },
                  "product": { "type": "string", "enum": ["recrawl", "featured"] }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "checkoutUrl" } }
      }
    },
    "/api/capabilities": {
      "get": {
        "summary": "Search named capabilities",
        "operationId": "searchCapabilities",
        "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Capability rows" } }
      }
    },
    "/api/discover": {
      "get": {
        "summary": "Discover MCP, payable, or OpenAPI sites",
        "operationId": "discoverSites",
        "parameters": [
          { "name": "need", "in": "query", "schema": { "type": "string", "enum": ["mcp", "payable", "openapi"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Discovery rows" } }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "Search MCP tools with a successful handshake",
        "operationId": "searchMcpTools",
        "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "MCP tool rows" } }
      }
    },
    "/api/mcp/rpc": {
      "get": {
        "summary": "AgentBoard MCP server card",
        "operationId": "mcpServerCard",
        "responses": { "200": { "description": "Server card" } }
      },
      "post": {
        "summary": "MCP JSON-RPC (initialize, tools/list, tools/call)",
        "operationId": "mcpRpc",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object" } } }
        },
        "responses": { "200": { "description": "JSON-RPC result" } }
      }
    },
    "/api/payable": {
      "get": {
        "summary": "Sites an agent can pay",
        "operationId": "searchPayable",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "max_usd", "in": "query", "schema": { "type": "number" } }
        ],
        "responses": { "200": { "description": "Payable rows" } }
      }
    },
    "/api/changes": {
      "get": {
        "summary": "Score diffs and hosts scanned since a date",
        "operationId": "changesSince",
        "parameters": [{ "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }],
        "responses": { "200": { "description": "Changes" } }
      }
    },
    "/api/site/{host}/history": {
      "get": {
        "summary": "Weekly snapshot score history for a host",
        "operationId": "siteHistory",
        "parameters": [{ "name": "host", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "History" } }
      }
    }
  },
  "components": {
    "schemas": {
      "ScanRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string" },
          "category": { "type": "string" }
        }
      },
      "ScanResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "host": { "type": "string" },
          "score": { "type": "integer" },
          "grade": { "type": "string" },
          "cached": { "type": "boolean" }
        }
      }
    },
    "securitySchemes": {
      "none": { "type": "http", "scheme": "bearer", "description": "Not required. Public API." }
    }
  }
}