← Back to blog

AgentBrowse API: Let AI Agents Read the Web with Verified Quotes

Every AI agent eventually needs to read a webpage. The naive approach — a bare fetch() or requests.get() — breaks the moment a site renders content with JavaScript, blocks datacenter IPs, or redirects through a chain you never audited. AgentBrowse is Agent Media Tools' answer: a goal-based web reading API designed for agents, with domain allowlists, SSRF-safe networking, and short evidence quotes you can actually verify.

It is a genuinely different tool from the structured scraping API. Scraping extracts fields against a JSON schema from a URL you already know. AgentBrowse is for research: you give it a goal like "summarize the pricing tiers on this page," it reads the page, and it returns clean text plus source quotes. You can call it over REST, or through the browse_web MCP tool that ships with the Agent Media Tools MCP server.

Why agents need a browser tool instead of raw fetch

A goal-based reader solves three problems a plain HTTP client cannot:

• JavaScript walls. Many pages render their real content in the browser. AgentBrowse's auto mode falls back to a local Companion or a cloud browser when plain HTTP is not enough, instead of returning an empty shell.
• Safety boundaries. Every request must list the public domains it is allowed to touch. Private networks and cloud metadata endpoints are blocked, redirects are re-checked against the allowlist, and response size and time are capped. This is the kind of guardrail you want before pointing an autonomous agent at the internet.
• Auditability. The response includes short quotes from the source page — each with a content_sha256 hash — so you can spot-check that the agent's summary is grounded in what the page actually said.

The API surface

All endpoints live under https://agentmediatools.com/api/:

Endpoint	Purpose	Auth
POST /api/browser/browse	Synchronous goal-based read	Bearer key or free daily
POST /api/browser/tasks	Async read, returns a task id	API key required
GET /api/browser/tasks/:taskId	Poll an async task	API key required
GET /api/browser/tasks	List your tasks	API key required
POST /api/browser/tasks/:taskId/cancel	Cancel a running task	API key required
GET /api/browser/companion	Companion online/offline status	API key or session
GET /api/browser/health	Runtime health	Public
POST /api/browser/mcp/browse_web	MCP-style alias of browse	Bearer key or free daily

Quick start with curl

The simplest synchronous read takes a goal and an allowed_domains list. A start_url is optional but recommended — it tells the reader where to begin, and its domain must be inside the allowlist.

curl -X POST "https://agentmediatools.com/api/browser/browse" \
  -H "Authorization: Bearer mt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "List the pricing tiers and their monthly prices.",
    "start_url": "https://example.com/pricing",
    "allowed_domains": ["example.com"],
    "mode": "auto"
  }'

Anonymous and free-plan identities get a daily allowance of 5 free browser-read calls, so you can try this exact command before creating a key. The response includes the task status, the extracted result, the evidence quotes, the mode that was actually used, and a billing object showing how many free reads remain:

{
  "success": true,
  "status": "completed",
  "result": { "summary": "...", "url": "https://example.com/pricing" },
  "evidence": [ { "quote": "...", "url": "...", "content_sha256": "..." } ],
  "mode_used": "http_read",
  "billing": { "tool": "browser-read", "free_remaining": 4 }
}

Reading the web from Python

Here is the same call with the requests library, including the optional success_conditions field that lets you declare what "done" means:

import requests

resp = requests.post(
    "https://agentmediatools.com/api/browser/browse",
    headers={"Authorization": "Bearer mt_live_YOUR_KEY"},
    json={
        "goal": "Find the support email address.",
        "start_url": "https://example.com/contact",
        "allowed_domains": ["example.com"],
        "success_conditions": ["email address found"],
    },
    timeout=90,
)
data = resp.json()
print(data["result"])
print(data["billing"]["free_remaining"])
if resp.headers.get("X-AgentBrowse-Free-Remaining"):
    print("free reads left:", resp.headers["X-AgentBrowse-Free-Remaining"])

The X-AgentBrowse-Free-Remaining response header is handy for agents that want to throttle themselves before they hit the paid tier.

Modes: auto, http_read, local_browser, cloud_browser

AgentBrowse has four modes, and in practice you can leave it on auto:

Mode	What happens	Cost
auto	Uses the Companion when online, otherwise server HTTP; escalates on JS walls	browser-read
http_read	Plain HTTP fetch on Agent Media Tools' side	browser-read
local_browser	Forces the page to load through your Companion from your own network	browser-read
cloud_browser	Full server-side Chromium/Playwright (operator-enabled)	browser-cloud (3 credits)

The Companion is a small desktop binary that downloads allowed public pages from your own computer and network, then returns structured text. It is not a remote desktop and it does not use your signed-in browser sessions. Check whether your Companion is online at any time:

curl "https://agentmediatools.com/api/browser/companion" \
  -H "Authorization: Bearer mt_live_YOUR_KEY"

You can download Companion for Linux, Windows, or macOS from the AgentBrowse product page, verify the published SHA-256 checksum, and pair it with your API key. For JS-heavy sites behind bot challenges, local_browser through your own network is often the most reliable path — and it is billed as the cheap browser-read tool, not the cloud browser.

Async tasks, idempotency, and webhooks

Long-running research should use the async task API. Create a task, then poll GET /api/browser/tasks/:taskId until it completes. Async endpoints require an API key, and they accept an Idempotency-Key header (8–128 letters, numbers, hyphens, or underscores) so retries never double-bill or double-run:

curl -X POST "https://agentmediatools.com/api/browser/tasks" \
  -H "Authorization: Bearer mt_live_YOUR_KEY" \
  -H "Idempotency-Key: research-example-2026-08-02" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Summarize the documentation overview.",
    "start_url": "https://example.com/docs",
    "allowed_domains": ["example.com"],
    "webhook_url": "https://your-app.example/hook"
  }'

# later: poll it
curl "https://agentmediatools.com/api/browser/tasks/TASK_ID" \
  -H "Authorization: Bearer mt_live_YOUR_KEY"

If you pass a webhook_url, the runtime can notify you when the task finishes — useful for pipeline jobs that should not sit and poll. Idempotent retries are stored per identity, and replaying the same key returns the original response with an Idempotent-Replayed header.

Using browse_web over MCP

If your agent talks MCP, the browse_web tool is already registered by the Agent Media Tools MCP server. Its inputs mirror the REST body: goal and allowed_domains are required; start_url, mode, and evidence are optional. From a Claude or any MCP-capable agent, you simply ask it to "read the docs on example.com and summarize the quickstart" — the model fills in the goal, and you stay inside the allowlist guardrails.

Pricing recap

• Free: 5 browser-read calls per day for anonymous and free-plan identities.
• Paid: 1 flexible credit per successful browser-read after the free allowance; the cloud browser is 3 credits per call.
• Refunds: if the upstream read fails, the credit gate is refunded automatically, so failed calls do not burn your balance.
• Premium plans raise the daily free allowance substantially (40 reads/day for browser-read on Founding Pro and higher plans).

The billing object on every response shows exactly what was charged and how much free allowance remains — no surprise metering.

When to use AgentBrowse

• Research agents that must cite sources and let a human verify quotes.
• Documentation and pricing monitors that hit JS-rendered pages a plain fetch cannot parse.
• Anything autonomous where you want a hard domain allowlist and SSRF protection baked in.

It is the tool I reach for whenever an agent needs to read a page and I need to sleep at night knowing it cannot wander onto internal networks or get stuck on a redirect loop.