{
  "openapi": "3.1.0",
  "info": {
    "title": "Bippsi Public API",
    "version": "1.0.0",
    "description": "Public endpoints for Bippsi. Most endpoints require Bearer authentication with an API key (bas_*, bak_*, bas_ak_*). See https://bippsi.com/AGENTS.md for the full agent access policy.",
    "contact": {
      "name": "Bippsi",
      "url": "https://bippsi.com/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://bippsi.com/policies"
    }
  },
  "servers": [
    { "url": "https://bippsi.com/api/v1", "description": "Production" }
  ],
  "paths": {
    "/validate": {
      "get": {
        "summary": "Validate an API key",
        "operationId": "validateKey",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Key is valid" },
          "401": { "description": "Invalid or missing key" }
        }
      }
    },
    "/verify-subscription": {
      "post": {
        "summary": "Verify an AI Certified subscription status",
        "operationId": "verifySubscription",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["site_key"],
                "properties": {
                  "site_key": { "type": "string" },
                  "site_url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "active": { "type": "boolean" },
                    "expires_at": { "type": "string", "format": "date-time", "nullable": true },
                    "config_hash": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/scan/{domain}": {
      "get": {
        "summary": "Get the latest AI Certified scan for a domain",
        "operationId": "getScan",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Scan summary" },
          "404": { "description": "No scan found" }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Model Context Protocol (MCP) JSON-RPC 2.0 endpoint for AI agents",
        "description": "Agents connect here to run compliance scans, discover pages, check certification status, and enumerate Bippsi endpoints without scraping HTML. Protocol: MCP 2024-11-05 over HTTP + JSON-RPC 2.0. Supported methods: initialize, tools/list, tools/call (tools: scan_site, list_pages, get_certification_status, get_api_endpoints), ping, notifications/initialized. Manifest: /.well-known/mcp.json. Rate limit: 60 calls/hr per IP overall, 3/hr for anonymous scan_site (unlimited with Bearer key).",
        "operationId": "mcpEndpoint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "id":      { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
                  "method":  { "type": "string", "description": "initialize | tools/list | tools/call | ping | notifications/initialized" },
                  "params":  { "type": "object" }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "scan_site",
                  "arguments": { "url": "https://example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "JSON-RPC 2.0 response with `result` or `error`." },
          "204": { "description": "No content (notifications only)." },
          "400": { "description": "JSON-RPC parse error." },
          "429": { "description": "Rate limit exceeded." }
        }
      },
      "get": {
        "summary": "MCP endpoint hint (human-browsable)",
        "operationId": "mcpHint",
        "description": "Returns a JSON summary of the MCP server for humans who browse the endpoint. Machines should POST JSON-RPC 2.0 messages instead.",
        "responses": {
          "200": { "description": "MCP server summary and quick-start hint" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "bas_*, bak_*, bas_ak_*"
      }
    }
  }
}