{"name":"w2agent API","description":"The w2agent API audits websites for AI agent readiness, generates AI-ready files such as llms.txt, deploys a website as a hosted MCP server agent, and serves the public directory of website agents. Responses are JSON unless an endpoint says otherwise. The OpenAPI 3.1 description covers the core operations and is the source of the endpoint list below. A few routes named in the rate-limit table, such as workflow execution and the llms.txt validator, are not in it yet.","baseUrl":"https://w2agent.dev","links":{"openapi":"https://w2agent.dev/openapi.json","docs":"https://w2agent.dev/docs/api","catalog":"https://w2agent.dev/.well-known/api-catalog","mcp":"https://agent.w2agent.dev/mcp"},"authentication":{"summary":"Most endpoints are public and need no credentials. Rate limits apply where the rate-limit table lists them, and hosted MCP agent endpoints are metered by the owner's plan quota. Endpoints that act on an account accept an API key or a signed-in browser session.","scheme":"HTTP Bearer","header":"Authorization: Bearer w2a_<token>","notes":["Create an API key at https://w2agent.dev/dashboard/api-keys. The full key is shown once, so store it when you create it.","A key acts for the account that created it.","An invalid key that starts with w2a_ is never treated as a browser session. Endpoints that need an account reject the call, and deploy handles it as an anonymous call.","Managing API keys (list, create, delete) needs a signed-in browser session. A key cannot manage keys."],"requirementLabels":{"public":"None (no credentials needed)","optional":"Optional API key or session (anonymous calls are allowed, with a lower daily allowance)","account":"API key or signed-in session","session":"Signed-in browser session only (API keys are not accepted)"}},"rateLimits":{"summary":"Every limit uses a sliding window. Most buckets are per IP address, and the table lists the exceptions.","tiers":[{"id":"expensive","name":"Expensive","limit":5,"window":"minute","per":"IP address","appliesTo":["POST /api/audit","POST /api/generate","POST /api/agent/deploy","PATCH /api/sites/{slug}/settings","POST /api/sites/{slug}/verify-dns","POST /api/tools/llms-txt-validate","POST /api/workflows/execute","POST /api/meta-agent","POST /api/meta-agent/a2a"]},{"id":"chat","name":"Chat","limit":1000,"window":"day","per":"IP address","appliesTo":["POST /api/sites/{slug}/chat"]},{"id":"chatPerSlug","name":"Chat per site","limit":60,"window":"minute","per":"site","appliesTo":["POST /api/sites/{slug}/chat"]},{"id":"deploy","name":"Anonymous deploy","limit":3,"window":"day","per":"IP address","appliesTo":["POST /api/agent/deploy"]},{"id":"submit","name":"Directory submission","limit":3,"window":"hour","per":"IP address","appliesTo":["POST /api/directory/submit","POST /api/directory/register"]},{"id":"directoryApi","name":"Directory API","limit":60,"window":"minute","per":"IP address","appliesTo":["GET /api/v0/servers","GET /api/v0/servers/{slug}"]},{"id":"recrawl","name":"Webhook re-crawl","limit":1,"window":"5 minutes","per":"site","appliesTo":["POST /api/agent/webhook/{slug}"]}],"notes":["Audit, generate and deploy share one bucket per IP address. Settings update, DNS verification, the llms.txt validator, workflow execution and the meta-agent endpoints (MCP and A2A together) each have their own bucket per IP address. The meta MCP tools audit_site and generate_files also charge the shared audit and generate bucket. Directory submit and register each have their own bucket.","Authenticated calls to deploy, settings update and DNS verification also share one further bucket of the same size, counted per API key or user.","A request blocked by a rate limiter returns HTTP 429 with a Retry-After header in seconds.","Audit, generate, deploy, chat, DNS verification and the llms.txt validator return HTTP 503 with Retry-After: 60 when the rate-limit store is unreachable.","Other endpoints fall back to an in-memory limit of 60 requests per 60 seconds per caller when that store is unreachable."]},"errors":{"summary":"Errors use an HTTP status code and a JSON body with an error string, for example {\"error\":\"Unauthorized\"}.","notes":["400 means the request body or parameters are invalid. 401 means a session is missing on the key management, billing and whoami endpoints. Settings update and DNS verification answer 403 when the key or session is missing or invalid, and also when the account does not own the site. 404 means the resource does not exist. 402 means the owner's plan quota for a hosted MCP agent is used up. 409 with code ownership_stale means the site's owner changed during a settings update or DNS verification, so retry the call.","POST /api/audit returns 422 with {\"error\":\"audit_failed\",\"kind\":\"...\",\"message\":\"...\"} when the target site could not be measured.","429 and 503 responses from the rate limiters carry a Retry-After header. A chat 429 for a site's daily query quota and a chat 503 when chat is not configured do not. Unexpected failures return 500 with a JSON error string.","The MCP and A2A endpoints report protocol errors as JSON-RPC error objects instead."]},"agents":{"summary":"How an AI agent authenticates with and calls the w2agent API.","steps":["Fetch /openapi.json (or /.well-known/api-catalog, which links to it) to learn the core operations and schemas.","Call public endpoints such as POST /api/audit or GET /api/v0/servers without a key. They are rate limited per IP address.","For account endpoints, send the header Authorization: Bearer w2a_<token>. A person creates the API key at /dashboard/api-keys and gives it to the agent.","On HTTP 429 or 503, wait for the number of seconds in the Retry-After header, then retry. If the header is absent, back off before retrying.","To use the directory without HTTP calls, connect an MCP client to the open meta MCP server at https://agent.w2agent.dev/mcp. It needs no key and is rate limited per IP address."]},"endpoints":[{"method":"POST","path":"/api/audit","summary":"Audit a website for agent-readiness","auth":"public"},{"method":"POST","path":"/api/generate","summary":"Generate AI-friendly output files","auth":"public"},{"method":"POST","path":"/api/agent/deploy","summary":"Deploy a website-agent as an MCP server","auth":"optional"},{"method":"GET","path":"/api/agent/{slug}","summary":"Get site info for an MCP server","auth":"public"},{"method":"POST","path":"/api/agent/{slug}","summary":"MCP JSON-RPC endpoint","auth":"public"},{"method":"GET","path":"/api/agent/{slug}/agent-card","summary":"Get A2A agent card for an MCP server","auth":"public"},{"method":"GET","path":"/api/agent/{slug}/server-json","summary":"Get MCP server manifest","auth":"public"},{"method":"GET","path":"/api/sites/{slug}/audit","summary":"Get latest audit for a site","auth":"public"},{"method":"POST","path":"/api/sites/{slug}/chat","summary":"Chat with a site's knowledge base","auth":"public"},{"method":"GET","path":"/api/sites/{slug}/badge.svg","summary":"Get w2agent score badge SVG","auth":"public"},{"method":"GET","path":"/api/sites/{slug}/llms.txt","summary":"Get llms.txt for a site","auth":"public"},{"method":"GET","path":"/api/sites/{slug}/llms-full.txt","summary":"Get llms-full.txt for a site","auth":"public"},{"method":"GET","path":"/api/sites/{slug}/skill.md","summary":"Get skill.md for a site","auth":"public"},{"method":"PATCH","path":"/api/sites/{slug}/settings","summary":"Update site settings","auth":"account"},{"method":"GET","path":"/api/sites/{slug}/verify-dns","summary":"Get DNS verification status","auth":"public"},{"method":"POST","path":"/api/sites/{slug}/verify-dns","summary":"Trigger DNS verification check","auth":"account"},{"method":"GET","path":"/api/v0/servers","summary":"List directory agents","auth":"public"},{"method":"GET","path":"/api/v0/servers/{slug}","summary":"Get a directory agent","auth":"public"},{"method":"GET","path":"/api/api-keys","summary":"List API keys","auth":"session"},{"method":"POST","path":"/api/api-keys","summary":"Create an API key","auth":"session"},{"method":"DELETE","path":"/api/api-keys/{id}","summary":"Delete an API key","auth":"session"},{"method":"GET","path":"/api/meta-agent","summary":"Get meta-agent server info","auth":"public"},{"method":"POST","path":"/api/meta-agent","summary":"Meta-agent JSON-RPC endpoint","auth":"public"},{"method":"GET","path":"/api/meta-agent/agent-card","summary":"Get A2A agent card for meta-agent","auth":"public"}]}