# Developer Docs: w2agent API

> Developer documentation for the w2agent API: base URL, API key authentication, rate limits, error format, the endpoint list and how AI agents call it, plus an interactive reference.

Source: https://w2agent.dev/docs/api

# w2agent API developer docs

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.

- [Overview](#overview)
- [Authentication](#authentication)
- [Rate limits](#rate-limits)
- [Errors](#errors)
- [Endpoints](#endpoints)
- [AI agents](#agents)
- [Resources](#resources)
- [Interactive reference](#reference)

## Overview

Base URL: `https://w2agent.dev`

## Authentication

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. Send the key in this header:

```
Authorization: Bearer w2a_<token>
```

- 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.

[Create an API key](/dashboard/api-keys) (https://w2agent.dev/dashboard/api-keys).

## Rate limits

Every limit uses a sliding window. Most buckets are per IP address, and the table lists the exceptions.

| Limit | Requests | Window | Counted per | Applies to |
| --- | --- | --- | --- | --- |
| Expensive | 5 | minute | IP address | POST /api/auditPOST /api/generatePOST /api/agent/deployPATCH /api/sites/{slug}/settingsPOST /api/sites/{slug}/verify-dnsPOST /api/tools/llms-txt-validatePOST /api/workflows/executePOST /api/meta-agentPOST /api/meta-agent/a2a |
| Chat | 1000 | day | IP address | POST /api/sites/{slug}/chat |
| Chat per site | 60 | minute | site | POST /api/sites/{slug}/chat |
| Anonymous deploy | 3 | day | IP address | POST /api/agent/deploy |
| Directory submission | 3 | hour | IP address | POST /api/directory/submitPOST /api/directory/register |
| Directory API | 60 | minute | IP address | GET /api/v0/serversGET /api/v0/servers/{slug} |
| Webhook re-crawl | 1 | 5 minutes | site | POST /api/agent/webhook/{slug} |

- 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

Errors use an HTTP status code and a JSON body with an error string, for example {"error":"Unauthorized"}.

- 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.

## Endpoints

| Method | Path | Summary | Authentication |
| --- | --- | --- | --- |
| POST | /api/audit | Audit a website for agent-readiness | None (no credentials needed) |
| POST | /api/generate | Generate AI-friendly output files | None (no credentials needed) |
| POST | /api/agent/deploy | Deploy a website-agent as an MCP server | Optional API key or session (anonymous calls are allowed, with a lower daily allowance) |
| GET | /api/agent/{slug} | Get site info for an MCP server | None (no credentials needed) |
| POST | /api/agent/{slug} | MCP JSON-RPC endpoint | None (no credentials needed) |
| GET | /api/agent/{slug}/agent-card | Get A2A agent card for an MCP server | None (no credentials needed) |
| GET | /api/agent/{slug}/server-json | Get MCP server manifest | None (no credentials needed) |
| GET | /api/sites/{slug}/audit | Get latest audit for a site | None (no credentials needed) |
| POST | /api/sites/{slug}/chat | Chat with a site's knowledge base | None (no credentials needed) |
| GET | /api/sites/{slug}/badge.svg | Get w2agent score badge SVG | None (no credentials needed) |
| GET | /api/sites/{slug}/llms.txt | Get llms.txt for a site | None (no credentials needed) |
| GET | /api/sites/{slug}/llms-full.txt | Get llms-full.txt for a site | None (no credentials needed) |
| GET | /api/sites/{slug}/skill.md | Get skill.md for a site | None (no credentials needed) |
| PATCH | /api/sites/{slug}/settings | Update site settings | API key or signed-in session |
| GET | /api/sites/{slug}/verify-dns | Get DNS verification status | None (no credentials needed) |
| POST | /api/sites/{slug}/verify-dns | Trigger DNS verification check | API key or signed-in session |
| GET | /api/v0/servers | List directory agents | None (no credentials needed) |
| GET | /api/v0/servers/{slug} | Get a directory agent | None (no credentials needed) |
| GET | /api/api-keys | List API keys | Signed-in browser session only (API keys are not accepted) |
| POST | /api/api-keys | Create an API key | Signed-in browser session only (API keys are not accepted) |
| DELETE | /api/api-keys/{id} | Delete an API key | Signed-in browser session only (API keys are not accepted) |
| GET | /api/meta-agent | Get meta-agent server info | None (no credentials needed) |
| POST | /api/meta-agent | Meta-agent JSON-RPC endpoint | None (no credentials needed) |
| GET | /api/meta-agent/agent-card | Get A2A agent card for meta-agent | None (no credentials needed) |

## AI agents

How an AI agent authenticates with and calls the w2agent API.

1. Fetch /openapi.json (or /.well-known/api-catalog, which links to it) to learn the core operations and schemas.
2. Call public endpoints such as POST /api/audit or GET /api/v0/servers without a key. They are rate limited per IP address.
3. 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.
4. 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.
5. 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.

## Resources

- [OpenAPI 3.1 description](https://w2agent.dev/openapi.json) `/openapi.json`
- [API catalog (RFC 9727)](https://w2agent.dev/.well-known/api-catalog) `/.well-known/api-catalog`
- [JSON API index](https://w2agent.dev/api) `/api`
- [Meta MCP server endpoint](https://agent.w2agent.dev/mcp) `https://agent.w2agent.dev/mcp`
