Agent Lens API

Keys and payment

Send your API key in the Authorization header: Bearer bhk_…. Free tools work without a key. A paid call with no key, or with too few credits, answers 402 Payment Required. A successful paid call returns the headers x-credits-charged and x-credits-remaining, and the same numbers in the billing field.

Credits are taken only after the call succeeds. A refusal or failure costs nothing.

x402 (agent pays per call in USDC): built, but not switched on yet. When it is, an unpaid call will answer 402 with the x402 v2 PAYMENT-REQUIRED header, and the agent pays with PAYMENT-SIGNATURE.

Fields every tool accepts

• url (required): an http or https page on a public address.
• user_agent: your own bot's robots.txt name. Agent Lens then checks that bot's rules as well as its own.
• engine: auto (default), fetch, kitesurf or chromium. With auto, the cheapest engine that gives a usable result wins, and the answer's attempts list shows what was tried.

POST /v1/site (free)

A site card for the site the URL belongs to. Returns llms_txt (found, title, summary, link count, the first 6,000 characters), llms_full_txt, sitemap (from robots.txt or /sitemap.xml: count and first 50 URLs), content_signals, ai_agents_at_root (allowed or disallowed for 15 known AI crawlers and agents), your_agent when you pass user_agent, and page (title, language, canonical URL, feeds, language versions, schema.org types).

POST /v1/preflight (free)

Returns allowed, policy (robots.txt rule, Content Signals, meta robots, X-Robots-Tag), needs (the engine for read, screenshot and interact, with reasons), signals (words in the HTML, script-built page, bot check, human check, sign-in form, video, WebGL libraries, forms) and prices_usd.

POST /v1/read (4 credits)

Options: max_chars (1,000–400,000; default 100,000). Returns markdown, title, words, links, truncated, engine_used, attempts.

POST /v1/extract (2 credits)

Returns jsonld (schema.org objects, including @graph), schema_types, offers (price, currency, availability, flattened), meta (description, Open Graph, Twitter, article and product tags), canonical, lang, languages, license, feeds and tables (up to 10 data tables, 50 rows each, as columns + rows).

POST /v1/delta (1 credit)

The first call returns every section of the page as changed_sections and a fingerprint. Keep the fingerprint and send it back as previous next time. The answer is then changed: false, or only the changed_sections and the headings in removed_sections, with words_saved. When the site supports ETag or Last-Modified, an unchanged page is detected without downloading it (checked_by: "http-304"). Agent Lens stores nothing between calls.

POST /v1/actions (4 credits)

Returns forms (action, method, fields with name, type, label and required, options for drop-downs, the submit button), buttons outside forms and links. Each element has a selector that matches exactly one element, or null when the page gives nothing unique; then use nth (the tag and its position, for example Playwright's locator("button").nth(2)).

POST /v1/screenshot (8 credits)

Options: engine (auto, kitesurf, chromium), full_page. Send Accept: image/png to get the image itself; otherwise the answer is JSON with image_base64.

GET /v1/credits (free)

Your key's remaining credits and their value in US dollars.

MCP server

Address: https://lens.bastionhelix.com/mcp (Streamable HTTP). Tools: preflight, site, read, extract, delta, actions, screenshot, credits, with the same fields as above. Add the header Authorization: Bearer bhk_… to the connection. Paid tools carry their price in their description.

Errors and limits

• 400 bad URL or option. 401 unknown key. 402 payment needed. 403 refused by robots.txt or Content Signals. 422 a bot check or the site refused the request. 429 too many requests. 502 no engine could load the page. 503 browser engines are unavailable. Errors are JSON: {"error": {"code", "message"}}. None of them are charged.
• Free tools: 30 calls a minute per IP address. Calls with a key: 120 a minute per key.
• Browser engines have a shared daily capacity. When it is used up, browser calls answer "busy" until the next day (UTC) and are not charged; plain-fetch calls keep working.
• Only public web addresses are accepted: no private networks, local hosts or non-standard ports.