AgentWeb API

Base URL for the runtime API: https://mcp.agentweb.us. The full machine-readable contract is the OpenAPI specification. 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

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.

{
  "domain": "asos.com",
  "action": "search_products",
  "params": { "q": "black linen shirt", "limit": "2" }
}

A real response (data trimmed):

{
  "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):

{
  "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_APPROVAL_REQUIRED`	402	Payment action has no approved purchase yet; `error.payment` has the approval URL
`PAYMENT_DECLINED`	402	A server-side payment guard refused (over cap, wrong merchant, expired)
`WORKSPACE_INACTIVE`	403	No active plan (trial ended); `error.credits` carries checkout guidance
`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. On failure, success is false with a typed error.code (AUTH_REQUIRED, INSUFFICIENT_CREDITS, UPSTREAM_APP_ERROR, …) plus a trace_id to quote in a bug report, and the credit reservation is refunded.

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

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)

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 — public MCP tool manifest
/.well-known/action-catalog.json — allowed and disallowed action families
/.well-known/sandbox.json — sandbox limits
/openapi.json — this API, fully specified

Get started

Connect

Reference

Commerce

Plans

Core runtime

Execute

Readiness and billing (www.agentweb.us)

Discovery surfaces

​Core runtime

​Execute

​Agent-native signup

​Readiness and billing (www.agentweb.us)

​Discovery surfaces

Core runtime

Execute

Agent-native signup

Readiness and billing (www.agentweb.us)

Discovery surfaces