> ## 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`. Browse every endpoint in the [API reference](https://www.agentweb.us/api-reference). The same contract is available as raw [OpenAPI JSON](https://www.agentweb.us/openapi.json) for tools and agents.

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

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

`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": "asos.com",
  "action": "search_products",
  "params": { "q": "black linen shirt", "limit": "2" }
}
```

A real response (data trimmed):

```json theme={null}
{
  "success": true,
  "domain": "asos.com",
  "action": "search_products",
  "data": {
    "kind": "json",
    "value": {
      "itemCount": 618,
      "products": [
        {
          "id": 210464145,
          "name": "ASOS DESIGN relaxed deep revere modal shirt in black",
          "price": { "current": { "value": 30, "text": "£30.00" }, "currency": "GBP" },
          "brandName": "ASOS DESIGN",
          "url": "asos-design/asos-design-relaxed-deep-revere-modal-shirt-in-black/prd/210464145"
        }
      ]
    }
  },
  "duration_ms": 2850,
  "map_version": "0.1.2",
  "billing": {
    "credits_charged": 1,
    "balance_remaining": 24999,
    "receipt_id": "awr_6ca354c4f1e95d0cde47e21d",
    "policy": "Credits are debited only on a verified completion; failed actions are refunded."
  }
}
```

A real failed response (unknown action; note the refund and `trace_id`):

```json theme={null}
{
  "success": false,
  "domain": "asos.com",
  "action": "nonexistent_action",
  "data": null,
  "error": {
    "code": "ACTION_NOT_FOUND",
    "message": "Action \"nonexistent_action\" not found on asos.com. Available actions: search_suggestions, search_products, search_products_by_category, get_product_summaries, get_delivery_countries, get_facet_enrichments."
  },
  "duration_ms": 3,
  "map_version": "0.1.2",
  "trace_id": "tr_66d8ed4bcb9a",
  "billing": {
    "credits_charged": 0,
    "balance_remaining": 24997,
    "receipt_id": "awr_be0ac634e868e971cd43090b",
    "policy": "Credits are debited only on a verified completion; failed actions are refunded."
  }
}
```

The complete `error.code` enum, with the HTTP status the REST lane returns:

| Code | HTTP | Meaning |
| - | - | - |
| `INVALID_PARAMS` | 400 | A param is missing or malformed; the message names it |
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits; `error.credits` carries the top-up link |
| `PAYMENT_DECLINED` | 402 | A server-side payment guard refused (over cap, wrong merchant, expired) |
| `BILLING_ACCOUNT_RESTRICTED` | 403 | Account barred from billed actions |
| `AUTH_REQUIRED` | 403 | Target-site connection needed; `error.auth` describes which |
| `AUTH_MISCONFIGURED` | 403 | The stored connection is broken; reconnect |
| `MAP_NOT_FOUND` / `ACTION_NOT_FOUND` | 404 | Domain not mapped / action not in the map (message lists available actions) |
| `RATE_LIMITED` | 429 | Slow down and retry after the window |
| `PAYMENT_NOT_SUPPORTED` | 501 | Terminal payment step not built for this merchant; nothing was charged |
| `UPSTREAM_ERROR` / `UPSTREAM_APP_ERROR` / `PARSE_ERROR` / `CURATED_MAP_STALE` | 502 | The target site failed (including 2xx transport whose payload reports failure) |
| `BILLING_UNAVAILABLE` | 503 | Ledger could not document the call, so it was not run; nothing charged |
| `TIMEOUT` | 504 | The mapped call timed out |

Every failure refunds the credit reservation and sets `trace_id`, a 7-day redacted trace you can quote in a support request. Over MCP the envelope above is returned directly; over REST, success wraps it as `{ "ok": true, "result": { ... }, "billing": { ... } }` and failure as `{ "ok": false, "error": { ... }, "trace_id": "...", "support_id": "awr_..." }` with the HTTP status from the table. Delegation codes for org workspaces (`MEMBER_NOT_LINKED`, `APPROVAL_PENDING`, `DELEGATION_DENIED`) carry `error.delegation`.

`billing.receipt_id` is the support receipt for the action. For actions where step success can diverge from job completion (checkouts, payments), the response adds an `outcome` object: `status` of `complete` (with `proof` such as an order ref), `partial` (with the exact `missing_step` and whether it is `safe_to_retry`), or `unavailable`.

* \~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 |

## Billing ([www.agentweb.us](http://www.agentweb.us))

| Endpoint | What it does |
| - | - |
| `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
* [`/api-reference`](https://www.agentweb.us/api-reference) — the same specification rendered for reading


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.