> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentweb.us/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentWeb API

> The AgentWeb REST surface: read, discover, execute, usage, agent-native signup, and billing, with the OpenAPI specification as the machine-readable contract.

Base URL for the runtime API: `https://mcp.agentweb.us`. The full machine-readable contract is the [OpenAPI specification](https://www.agentweb.us/openapi.json).

Authenticated endpoints take an AgentWeb key in the header:

```
Authorization: Bearer aw_<key>
```

## Core runtime

| Endpoint                 | Auth      | What it does                                                                   |
| ------------------------ | --------- | ------------------------------------------------------------------------------ |
| `GET/POST /api/read`     | `aw_` key | Fetch a public URL as clean text, links, forms, and metadata                   |
| `GET/POST /api/discover` | `aw_` key | Learned action-map context for a domain: exact action names and parameter keys |
| `POST /api/execute`      | `aw_` key | **Execute a mapped site action** and get a typed result                        |
| `GET /api/usage`         | `aw_` key | Spendable credit balance, effective plan, and metering policy                  |

### Execute

<Info>`execute` is the core of AgentWeb: \~1 credit per completed action, failed actions refunded, and a verified receipt on every task.</Info>

`POST /api/execute` runs one of the verified actions AgentWeb has learned for a supported domain. Get exact action names and parameter keys from `/api/discover` first.

```json theme={null}
{
  "domain": "example.com",
  "action": "search_products",
  "params": { "query": "desk lamp", "page": 1 }
}
```

* \~1 credit per completed action; **failed actions are refunded**.
* Send an `Idempotency-Key` header on retries — the same key maps to the same billing task, so a retried call is never charged twice.
* Treat the returned status, verification artifact, or structured failure as the source of truth; never infer completion from an accepted request.

## Agent-native signup

| Endpoint               | What it does                                                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `POST /agent/identity` | Start one-link onboarding: returns a `device_code` and verification URI to show the human            |
| `POST /oauth2/token`   | Exchange a connected `device_code` for an `aw_` key (pending devices return `authorization_pending`) |
| `POST /api/register`   | Email-code fallback: sends a verification code, returns a `deviceId`                                 |
| `POST /api/verify`     | Verify the email code and receive the `aw_` key plus MCP setup command                               |

## Readiness and billing ([www.agentweb.us](http://www.agentweb.us))

| Endpoint                                    | What it does                                                            |
| ------------------------------------------- | ----------------------------------------------------------------------- |
| `POST /api/readiness/scan`                  | Public company-URL audit for agent discoverability and executionability |
| `GET /api/billing/account`                  | The authenticated customer's plan, credits, and action receipts         |
| `POST /api/billing/create-checkout-session` | Dodo hosted checkout handoff                                            |
| `POST /api/billing/webhook`                 | Signed Dodo billing webhook receiver                                    |

## Discovery surfaces

* [`/.well-known/mcp/tools.json`](https://mcp.agentweb.us/.well-known/mcp/tools.json) — public MCP tool manifest
* [`/.well-known/action-catalog.json`](https://www.agentweb.us/.well-known/action-catalog.json) — allowed and disallowed action families
* [`/.well-known/sandbox.json`](https://www.agentweb.us/.well-known/sandbox.json) — sandbox limits
* [`/openapi.json`](https://www.agentweb.us/openapi.json) — this API, fully specified