{
  "openapi": "3.1.0",
  "info": {
    "title": "w2agent API",
    "description": "Agentize websites as hosted MCP server agents, audit sites for agent-readiness, and generate AI-ready files.\n\n## Authentication\n\nMost endpoints are public and need no credentials. Rate limits apply where the table below lists them, and hosted MCP agent endpoints are metered by the owner's plan quota. Authenticated endpoints accept either:\n- **Bearer API Key**: `Authorization: Bearer w2a_<token>` — get one at [/dashboard/api-keys](https://w2agent.dev/dashboard/api-keys)\n- **Clerk Session**: Browser cookie session (not available for programmatic access)\n\n## Rate Limits\n\nLimits are per IP address unless noted. Authenticated calls to deploy, settings PATCH and verify-dns POST also count against a second 5 req/min bucket for the key or user.\n\n| Tier | Limit | Applies To |\n|------|-------|------------|\n| Expensive | 5 req/min | audit, generate, deploy, settings PATCH, verify-dns POST, llms.txt validator, workflow execute, meta-agent MCP and A2A |\n| Chat | 1000 req/day per IP, plus 60 req/min per site | /api/sites/{slug}/chat |\n| Anonymous deploy | 3 req/day per IP | /api/agent/deploy without an account |\n| Directory submit | 3 req/hour per IP | /api/directory/submit, /api/directory/register |\n| Directory API | 60 req/min per IP | /api/v0/servers |\n| Webhook re-crawl | 1 req/5 min per site | /api/agent/webhook/{slug} |\n\nRate-limited responses return HTTP 429 with a `Retry-After` header (seconds). Some endpoints return 503 with `Retry-After: 60` when the rate-limit store is unreachable.\n\n## Streaming\n\nSeveral endpoints support Server-Sent Events (SSE) streaming. Pass `\"stream\": true` in the request body to receive incremental progress. SSE events follow this format:\n\n```\ndata: {\"type\":\"progress\",\"data\":\"Crawling page 3 of 10...\"}\n\ndata: {\"type\":\"result\",\"data\":{...finalResult}}\n\ndata: {\"type\":\"error\",\"data\":\"Something went wrong\"}\n\n```\n\nThe chat endpoint uses Vercel AI SDK SSE format (different from the above).",
    "version": "1.0.0",
    "contact": {
      "url": "https://w2agent.dev"
    }
  },
  "servers": [
    {
      "url": "https://w2agent.dev",
      "description": "Production"
    }
  ],
  "security": [],
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with `w2a_` prefix. Create one at https://w2agent.dev/dashboard/api-keys"
      },
      "ClerkSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "__session",
        "description": "Signed-in browser session. Used by the dashboard; not available to programmatic clients."
      }
    },
    "schemas": {
      "DirectoryServer": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": ["string", "null"]
          },
          "description": {
            "type": ["string", "null"]
          },
          "url": {
            "type": "string"
          },
          "category": {
            "type": ["string", "null"]
          },
          "hosting_type": {
            "type": "string",
            "description": "w2agent-hosted, self-hosted or external"
          },
          "health_status": {
            "type": "string"
          },
          "agent_endpoint": {
            "type": "string"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audit_score": {
            "type": ["integer", "null"],
            "description": "null when never scored or the latest audit attempt did not succeed"
          },
          "audit_grade": {
            "type": ["string", "null"]
          },
          "quality_score": {
            "type": ["number", "null"]
          },
          "benchmark_rating": {
            "type": ["number", "null"]
          },
          "pages_indexed": {
            "type": ["integer", "null"]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DirectoryServerDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DirectoryServer"
          },
          {
            "type": "object",
            "properties": {
              "tools": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Raw MCP tool names"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Invalid URL"
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "example": "Rate limited. Retry after 60 seconds."
          }
        }
      },
      "AuditReport": {
        "type": "object",
        "description": "Agent-readiness audit results for a website. Additional fields may be present beyond those listed here.",
        "properties": {
          "auditId": {
            "type": ["string", "null"],
            "description": "Stored audit ID (present if the audit was persisted)"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Overall w2agent score"
          },
          "grade": {
            "type": "string",
            "enum": ["A", "B", "C", "D", "F"]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "score": { "type": "number" },
                "passed": { "type": "boolean" },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "GenerateResult": {
        "type": "object",
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "filename": { "type": "string" },
                "content": { "type": "string" }
              }
            }
          },
          "totalPagesFound": { "type": "integer" }
        }
      },
      "DeployResult": {
        "type": "object",
        "required": ["slug", "url", "agentEndpoint"],
        "properties": {
          "slug": { "type": "string", "example": "example-com" },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example-com.agent.w2agent.dev"
          },
          "agentEndpoint": {
            "type": "string",
            "format": "uri",
            "example": "https://example-com.agent.w2agent.dev/mcp"
          },
          "agentCard": { "type": "string", "format": "uri" },
          "serverJson": { "type": "string", "format": "uri" },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" }
              }
            }
          },
          "pagesIndexed": { "type": "integer" },
          "totalPagesFound": { "type": "integer" },
          "webhookToken": { "type": "string" },
          "webhookUrl": { "type": "string", "format": "uri" },
          "dnsToken": { "type": "string" },
          "dnsVerifyRecord": { "type": "string", "example": "_w2agent.example.com" },
          "dnsVerifyValue": { "type": "string", "example": "w2agent-verify=abc12345" },
          "llmsTxt": { "type": "string", "format": "uri" },
          "llmsFullTxt": { "type": "string", "format": "uri" },
          "skillMd": { "type": "string", "format": "uri" },
          "badgeUrl": { "type": "string", "format": "uri" },
          "isRedeploy": { "type": "boolean" }
        }
      },
      "SiteInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "sourceUrl": { "type": "string", "format": "uri" },
          "tools": {
            "type": "array",
            "items": { "type": "string" }
          },
          "pagesIndexed": { "type": "integer" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "auditScore": { "type": ["number", "null"] },
          "auditGrade": { "type": ["string", "null"] },
          "agentEndpoint": { "type": "string", "format": "uri" }
        }
      },
      "SiteSettings": {
        "type": "object",
        "properties": {
          "crawlFrequency": {
            "type": ["string", "null"],
            "enum": ["manual", "daily", "weekly", "monthly", null]
          },
          "maxPages": { "type": ["integer", "null"] },
          "chatSystemPrompt": { "type": ["string", "null"] },
          "includePaths": {
            "type": ["string", "null"],
            "description": "Comma-separated path prefixes to include during crawl"
          },
          "excludePaths": {
            "type": ["string", "null"],
            "description": "Comma-separated path prefixes to exclude during crawl"
          },
          "queryDailyLimit": {
            "type": ["integer", "null"],
            "description": "Daily MCP query cap for this site"
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "prefix": { "type": "string", "example": "w2a_abc1" },
          "createdAt": { "type": "string", "format": "date-time" },
          "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "DnsVerifyStatus": {
        "type": "object",
        "properties": {
          "verified": { "type": "boolean" },
          "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
          "domain": { "type": "string" },
          "record": { "type": "string", "example": "_w2agent.example.com" },
          "value": { "type": ["string", "null"], "example": "w2agent-verify=abc12345" }
        }
      },
      "AgentCard": {
        "type": "object",
        "description": "A2A (Agent-to-Agent) protocol agent card",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "version": { "type": "string" },
          "capabilities": { "type": "object" },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "name": { "type": "string" },
                "description": { "type": "string" }
              }
            }
          }
        }
      },
      "McpRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "description": "JSON-RPC 2.0 request (MCP protocol)",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "method": {
            "type": "string",
            "example": "tools/list",
            "description": "MCP method name, e.g. `tools/list`, `tools/call`, `initialize`"
          },
          "params": { "type": "object" }
        },
        "example": {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "tools/list",
          "params": {}
        }
      },
      "McpRpcResponse": {
        "type": "object",
        "description": "JSON-RPC 2.0 response (MCP protocol)",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "integer", "null"] },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" }
            }
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["user", "assistant"] },
          "content": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request — missing or invalid parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication required",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "Unauthorized" }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated but not permitted (e.g. not the site owner)",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "Forbidden" }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "Site not found" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Check the `Retry-After` header for when to retry.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the rate limit resets",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/RateLimitError" }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Directory",
      "description": "Public directory of website agents (v0, format may change before v1)"
    },
    {
      "name": "Audit",
      "description": "Audit a website for agent-readiness"
    },
    {
      "name": "Generate",
      "description": "Generate llms.txt and other AI-friendly outputs"
    },
    {
      "name": "Deploy",
      "description": "Deploy a website-agent as an MCP server"
    },
    {
      "name": "Sites",
      "description": "Site metadata, settings, and DNS verification"
    },
    {
      "name": "MCP",
      "description": "MCP protocol endpoints and agent discovery"
    },
    {
      "name": "Chat",
      "description": "Chat with a site's knowledge base"
    },
    {
      "name": "Content",
      "description": "Machine-readable content files (llms.txt, skill.md, badge)"
    },
    {
      "name": "API Keys",
      "description": "Manage API keys (requires browser Clerk session — not accessible via API key)"
    },
    {
      "name": "Meta Agent",
      "description": "Aggregated agent server for the w2agent directory"
    }
  ],
  "paths": {
    "/api/audit": {
      "post": {
        "tags": ["Audit"],
        "operationId": "auditUrl",
        "summary": "Audit a website for agent-readiness",
        "description": "Crawls the given URL and scores it for agent-readiness across multiple checks including llms.txt presence, structured data, robots.txt compliance, and more. Returns a w2agent score. Supports streaming via SSE.\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Website URL to audit",
                    "example": "https://example.com"
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "maxPages": {
                        "type": "integer",
                        "default": 10,
                        "maximum": 20,
                        "description": "Maximum pages to crawl"
                      }
                    }
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, returns an SSE stream with progress events instead of waiting for the final JSON result"
                  }
                }
              },
              "example": {
                "url": "https://example.com",
                "stream": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit complete. Returns JSON when `stream` is false, or SSE stream when `stream` is true.\n\nSSE events: `progress` (string status), `result` (AuditReport), `error` (string message).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuditReport" }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE stream. Each event: `data: {\"type\":\"progress\"|\"result\"|\"error\",\"data\":...}\\n\\n`"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/generate": {
      "post": {
        "tags": ["Generate"],
        "operationId": "generateFiles",
        "summary": "Generate AI-friendly output files",
        "description": "Crawls the given URL and generates one or more output files (llms.txt, agent card, schema.org markup, etc.). Supports streaming via SSE.\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://example.com"
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "maxPages": {
                        "type": "integer",
                        "default": 10,
                        "maximum": 20
                      },
                      "formats": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "llms-txt",
                            "full",
                            "robots-txt",
                            "schema-org",
                            "agent-card",
                            "faq",
                            "skill-md",
                            "mcp-server"
                          ]
                        },
                        "description": "Output formats to generate. Defaults to all formats."
                      }
                    }
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, returns an SSE stream with progress events"
                  }
                }
              },
              "example": {
                "url": "https://example.com",
                "options": { "formats": ["llms-txt", "skill-md"] },
                "stream": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation complete. Returns JSON when `stream` is false, SSE stream when true.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateResult" }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE stream. Each event: `data: {\"type\":\"progress\"|\"result\"|\"error\",\"data\":...}\\n\\n`"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/agent/deploy": {
      "post": {
        "tags": ["Deploy"],
        "operationId": "deploySite",
        "summary": "Deploy a website-agent as an MCP server",
        "description": "Agentizes the given URL — crawls it, builds an MCP server, and hosts it on a subdomain. If a site with the given slug already exists, re-agentizes with fresh content.\n\nAuthentication is optional — unauthenticated deploys work but limits apply.\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [{}, { "BearerApiKey": [] }, { "ClerkSession": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://example.com"
                  },
                  "slug": {
                    "type": "string",
                    "description": "Custom slug for the MCP server (auto-generated from domain if omitted)",
                    "example": "example-com"
                  },
                  "auditScore": {
                    "type": "number",
                    "description": "Pre-computed w2agent score to attach (avoids re-auditing)"
                  },
                  "auditGrade": {
                    "type": "string",
                    "enum": ["A", "B", "C", "D", "F"],
                    "description": "Pre-computed w2agent score grade to attach"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, returns an SSE stream with progress events"
                  }
                }
              },
              "example": {
                "url": "https://example.com",
                "stream": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deploy complete. Returns JSON when `stream` is false, SSE stream when true.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DeployResult" }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE stream. Each event: `data: {\"type\":\"progress\"|\"result\"|\"error\",\"data\":...}\\n\\n`"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/agent/{slug}": {
      "get": {
        "tags": ["MCP"],
        "operationId": "getMcpSiteInfo",
        "summary": "Get site info for an MCP server",
        "description": "Returns metadata about a deployed MCP server / website-agent.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Site slug (e.g. `example-com`)",
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "Site info",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SiteInfo" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "tags": ["MCP"],
        "operationId": "mcpJsonRpc",
        "summary": "MCP JSON-RPC endpoint",
        "description": "JSON-RPC 2.0 endpoint implementing the Model Context Protocol. Use `tools/list` to discover available tools and `tools/call` to invoke them.\n\n**This is not a standard REST endpoint.** It uses JSON-RPC 2.0 semantics. Quota limits apply based on the site's plan.\n\n**Common methods**: `initialize`, `tools/list`, `tools/call`, `resources/list`, `prompts/list`",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/McpRpcRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/McpRpcResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/agent/{slug}/agent-card": {
      "get": {
        "tags": ["MCP"],
        "operationId": "getMcpAgentCard",
        "summary": "Get A2A agent card for an MCP server",
        "description": "Returns an [A2A (Agent-to-Agent) protocol](https://google.github.io/A2A/) agent card describing the site's capabilities.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "A2A agent card",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentCard" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/{slug}/server-json": {
      "get": {
        "tags": ["MCP"],
        "operationId": "getMcpServerJson",
        "summary": "Get MCP server manifest",
        "description": "Returns the MCP `server.json` manifest describing the server's tools, capabilities, and endpoint URLs.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "MCP server manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "MCP server.json manifest"
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/audit": {
      "get": {
        "tags": ["Audit"],
        "operationId": "getSiteAudit",
        "summary": "Get latest audit for a site",
        "description": "Returns the most recent stored audit for a deployed site.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "Latest audit report",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuditReport" }
              }
            }
          },
          "202": {
            "description": "Audit is pending (crawl in progress)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["pending"] }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/chat": {
      "post": {
        "tags": ["Chat"],
        "operationId": "chatWithSite",
        "summary": "Chat with a site's knowledge base",
        "description": "Streams an AI-generated response grounded in the site's indexed content. Uses Vercel AI SDK SSE format.\n\n**Rate limit**: 1000 requests/day per IP.\n\n**Streaming format**: This endpoint uses Vercel AI SDK protocol, which differs from other SSE endpoints. The response is a stream of text delta chunks.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/ChatMessage" },
                    "description": "Conversation history. Last message should have role `user`."
                  }
                }
              },
              "example": {
                "messages": [{ "role": "user", "content": "What does this site do?" }]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI SDK SSE stream with text deltas",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Vercel AI SDK streaming protocol"
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/sites/{slug}/badge.svg": {
      "get": {
        "tags": ["Content"],
        "operationId": "getSiteBadge",
        "summary": "Get w2agent score badge SVG",
        "description": "Returns an SVG badge showing the site's w2agent score grade. Embeddable in READMEs and websites.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "SVG badge",
            "content": {
              "image/svg+xml": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/llms.txt": {
      "get": {
        "tags": ["Content"],
        "operationId": "getSiteLlmsTxt",
        "summary": "Get llms.txt for a site",
        "description": "Returns the site's `llms.txt` file — a concise, LLM-optimized summary of the site's content following the [llmstxt.org](https://llmstxt.org) standard.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "llms.txt content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/llms-full.txt": {
      "get": {
        "tags": ["Content"],
        "operationId": "getSiteLlmsFullTxt",
        "summary": "Get llms-full.txt for a site",
        "description": "Returns the full-length version of the site's `llms.txt` file, including complete page content for all indexed pages.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "llms-full.txt content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/skill.md": {
      "get": {
        "tags": ["Content"],
        "operationId": "getSiteSkillMd",
        "summary": "Get skill.md for a site",
        "description": "Returns a Markdown skill definition file that LLM agents can use to understand how to interact with this site's MCP server.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "skill.md content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/sites/{slug}/settings": {
      "patch": {
        "tags": ["Sites"],
        "operationId": "updateSiteSettings",
        "summary": "Update site settings",
        "description": "Updates settings for a deployed site. Requires authentication and ownership of the site.\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [{ "BearerApiKey": [] }, { "ClerkSession": [] }],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SiteSettings" },
              "example": {
                "crawlFrequency": "weekly",
                "maxPages": 50
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated settings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "settings": { "$ref": "#/components/schemas/SiteSettings" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/sites/{slug}/verify-dns": {
      "get": {
        "tags": ["Sites"],
        "operationId": "getDnsVerifyStatus",
        "summary": "Get DNS verification status",
        "description": "Returns the current DNS verification status for custom domain setup.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "DNS verification status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DnsVerifyStatus" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "tags": ["Sites"],
        "operationId": "triggerDnsVerify",
        "summary": "Trigger DNS verification check",
        "description": "Performs a live DNS TXT lookup to verify domain ownership. Requires authentication and ownership of the site.\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [{ "BearerApiKey": [] }, { "ClerkSession": [] }],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "example-com"
          }
        ],
        "responses": {
          "200": {
            "description": "DNS verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": { "type": "boolean" },
                    "message": { "type": "string" },
                    "expected": {
                      "type": "object",
                      "properties": {
                        "record": { "type": "string", "example": "_w2agent.example.com" },
                        "value": { "type": "string", "example": "w2agent-verify=abc12345" }
                      }
                    }
                  }
                },
                "example": {
                  "verified": false,
                  "message": "TXT record not found",
                  "expected": {
                    "record": "_w2agent.example.com",
                    "value": "w2agent-verify=abc12345"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v0/servers": {
      "get": {
        "tags": ["Directory"],
        "operationId": "listDirectoryServers",
        "summary": "List directory agents",
        "description": "Search and list directory agents with filtering and pagination. Public, no credentials. Rate limit: 60 req/min per IP. v0: the format may change before v1.",
        "security": [],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Text search (slug, URL, display name)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Exact category match",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capability",
            "in": "query",
            "required": false,
            "description": "Capability filter",
            "schema": {
              "type": "string",
              "enum": ["faq", "forms", "native-search", "api", "commerce"]
            }
          },
          {
            "name": "hosting_type",
            "in": "query",
            "required": false,
            "description": "Hosting type",
            "schema": {
              "type": "string",
              "enum": ["w2agent-hosted", "self-hosted", "external"]
            }
          },
          {
            "name": "min_score",
            "in": "query",
            "required": false,
            "description": "Minimum audit score (sites whose latest audit failed are excluded)",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Page offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "servers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DirectoryServer"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v0/servers/{slug}": {
      "get": {
        "tags": ["Directory"],
        "operationId": "getDirectoryServer",
        "summary": "Get a directory agent",
        "description": "Returns full metadata for one directory agent, including its raw MCP tool names. Public, no credentials. Rate limit: 60 req/min per IP.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryServerDetail"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/api-keys": {
      "get": {
        "tags": ["API Keys"],
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "description": "Returns all API keys for the authenticated user. **Requires a browser Clerk session** — this endpoint cannot be accessed with a Bearer API key (that would be circular).",
        "security": [{ "ClerkSession": [] }],
        "responses": {
          "200": {
            "description": "List of API keys (key values are never returned after creation)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ApiKey" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["API Keys"],
        "operationId": "createApiKey",
        "summary": "Create an API key",
        "description": "Creates a new API key. The full key value is returned **once** — store it securely. **Requires a browser Clerk session.**",
        "security": [{ "ClerkSession": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Human-readable label for this key",
                    "example": "My production key"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created API key (key value shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "key": {
                      "type": "string",
                      "description": "Full API key value — shown once, store securely",
                      "example": "w2a_abc123xyz..."
                    },
                    "prefix": { "type": "string", "example": "w2a_abc1" },
                    "name": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/api-keys/{id}": {
      "delete": {
        "tags": ["API Keys"],
        "operationId": "deleteApiKey",
        "summary": "Delete an API key",
        "description": "Permanently revokes an API key. **Requires a browser Clerk session.**",
        "security": [{ "ClerkSession": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" },
            "description": "API key ID (from the list endpoint)",
            "example": 42
          }
        ],
        "responses": {
          "200": {
            "description": "Key deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/meta-agent": {
      "get": {
        "tags": ["Meta Agent"],
        "operationId": "getMetaMcpInfo",
        "summary": "Get meta-agent server info",
        "description": "Returns metadata about the w2agent meta-agent server, which aggregates all deployed website-agents into a single agent endpoint.",
        "security": [],
        "responses": {
          "200": {
            "description": "Meta-agent server info",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SiteInfo" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Meta Agent"],
        "operationId": "metaMcpJsonRpc",
        "summary": "Meta-agent JSON-RPC endpoint",
        "description": "JSON-RPC 2.0 endpoint for the aggregated meta-agent server. Exposes tools across all deployed website-agents.\n\n**Available tools**: `search_websites`, `get_website_info`, `query_website`\n\n**Rate limit**: 5 requests/minute per IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/McpRpcRequest" },
              "examples": {
                "tools_list": {
                  "summary": "List available tools",
                  "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }
                },
                "search_websites": {
                  "summary": "Search websites",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/call",
                    "params": {
                      "name": "search_websites",
                      "arguments": { "query": "documentation site" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/McpRpcResponse" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/meta-agent/agent-card": {
      "get": {
        "tags": ["Meta Agent"],
        "operationId": "getMetaMcpAgentCard",
        "summary": "Get A2A agent card for meta-agent",
        "description": "Returns an A2A protocol agent card for the w2agent meta-agent server.",
        "security": [],
        "responses": {
          "200": {
            "description": "A2A agent card",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentCard" }
              }
            }
          }
        }
      }
    }
  }
}
