{"openapi":"3.1.0","info":{"title":"AgentReader","version":"0.4.1","description":"Your agent's built-in fetch often fails on real-world pages: JavaScript-only sites come back empty, cookie and consent walls replace the content, PDFs arrive as binary, and ordinary HTML wastes thousands of tokens on menus, ads and scripts. AgentReader returns the page's actual content as clean, compact Markdown or JSON (title, author, date, links, tables). If a site blocks bots, it fails fast with a clear error and you are not charged. Also: web search, field extraction (extract=), RSS/Atom feeds. REST API + remote MCP server. 5 free reads/day with no signup, then $0.005 per call in USDC via x402 (no account) or prepaid credits.","contact":{"email":"contact@agentreader.xyz"},"x-guidance":"To read a URL and pay per call: GET https://agentreader.xyz/v1/x402/read?url=<http(s) URL>&format=json|markdown. Without a payment header the server returns HTTP 402 with an x402 v2 challenge (PAYMENT-REQUIRED header, $0.005 USDC on eip155:8453); sign it and retry with PAYMENT-SIGNATURE. For many calls, buy prepaid credits with POST https://agentreader.xyz/v1/credits/buy?bundle=500 ($1, x402); the response returns an API key, then call GET https://agentreader.xyz/v1/read?url=... with Authorization: Bearer <key>. JSON output: title, author, date, markdown, links, tables. Works for HTML, JS-rendered pages and PDFs."},"servers":[{"url":"https://agentreader.xyz"}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","description":"Optional API key holding prepaid credits (ar_...)"}}},"paths":{"/v1/x402/read":{"get":{"operationId":"readUrlPaid","description":"Read a web page or PDF and get its main content as clean, compact Markdown (default) or JSON. Use when a normal fetch returns an empty JavaScript shell, a cookie/consent page, raw PDF bytes, or bloated HTML full of navigation and ads. Renders JavaScript with headless Chromium when needed, accepts consent walls, and strips boilerplate. JSON adds title, author, date, links and tables. News homepages return headline lists, RSS/Atom feeds return items, mode=full returns the whole page. StackOverflow, npm and PyPI are read via their official APIs. Sites that block bots fail fast with a clear error and are not charged.","tags":["read"],"summary":"Read a URL (always paid: $0.005 USDC via x402)","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"network":"eip155:8453","asset":"USDC"},"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"The page, PDF or RSS/Atom feed to read. Also accepted as u or link, without https://, or path style /v1/read/https://…."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["markdown","json"]},"description":"markdown returns the content as Markdown only. json wraps the same Markdown with title, author, date, word count, links, tables and metadata (meta.warning flags results that may be incomplete); there is no separate plain-text copy. Default: markdown."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["auto","article","links","full"]},"description":"article: main content only. links: list of headlines with links. full: the whole page, including non-article parts. auto picks article or links based on the page. RSS/Atom feeds always return their items. Default: auto."},{"name":"render","in":"query","required":false,"schema":{"type":"string","enum":["auto","never","always"]},"description":"Whether to load the page in headless Chromium. auto does so only when plain fetching returns too little. Default: auto."},{"name":"extract","in":"query","required":false,"schema":{"type":"string"},"description":"Returns named fields (title, author, date, price, currency, image, brand, sku, rating, availability, summary…) from JSON-LD, OpenGraph, microdata and meta tags. No LLM. Missing fields are null. In JSON as `fields`, in Markdown as front matter. Default: (none)."}],"responses":{"200":{"description":"Markdown (text/markdown) or JSON","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","description":"format=markdown returns text/markdown; format=json returns this object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"author":{"type":["string","null"]},"date":{"type":["string","null"]},"siteName":{"type":["string","null"]},"description":{"type":["string","null"]},"contentType":{"type":"string","enum":["html","pdf","feed"]},"pageType":{"type":"string","enum":["article","index","feed","pdf"]},"items":{"type":"array","description":"Headlines (index pages) or feed items: {title, link, date?, summary?}"},"markdown":{"type":"string"},"wordCount":{"type":"number"},"links":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"href":{"type":"string"}}}},"tables":{"type":"array","items":{"type":"object","properties":{"caption":{"type":"string"},"headers":{"type":"array"},"rows":{"type":"array"}}}}}}}}},"402":{"description":"x402 payment required (USDC)","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number"},"accepts":{"type":"array"}}}}}}}},"post":{"operationId":"readUrlPaidPost","description":"Read a web page or PDF and get its main content as clean, compact Markdown (default) or JSON. Use when a normal fetch returns an empty JavaScript shell, a cookie/consent page, raw PDF bytes, or bloated HTML full of navigation and ads. Renders JavaScript with headless Chromium when needed, accepts consent walls, and strips boilerplate. JSON adds title, author, date, links and tables. News homepages return headline lists, RSS/Atom feeds return items, mode=full returns the whole page. StackOverflow, npm and PyPI are read via their official APIs. Sites that block bots fail fast with a clear error and are not charged.","tags":["read"],"summary":"Read a URL (always paid, JSON body)","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"network":"eip155:8453","asset":"USDC"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The page, PDF or RSS/Atom feed to read. Also accepted as u or link, without https://, or path style /v1/read/https://…."},"format":{"type":"string","enum":["markdown","json"],"description":"markdown returns the content as Markdown only. json wraps the same Markdown with title, author, date, word count, links, tables and metadata (meta.warning flags results that may be incomplete); there is no separate plain-text copy. Default: markdown."},"mode":{"type":"string","enum":["auto","article","links","full"],"description":"article: main content only. links: list of headlines with links. full: the whole page, including non-article parts. auto picks article or links based on the page. RSS/Atom feeds always return their items. Default: auto."},"render":{"type":"string","enum":["auto","never","always"],"description":"Whether to load the page in headless Chromium. auto does so only when plain fetching returns too little. Default: auto."},"extract":{"type":"string","description":"Returns named fields (title, author, date, price, currency, image, brand, sku, rating, availability, summary…) from JSON-LD, OpenGraph, microdata and meta tags. No LLM. Missing fields are null. In JSON as `fields`, in Markdown as front matter. Default: (none)."},"nocache":{"type":"string","enum":["1"],"description":"Skips the 10-minute result cache and reads the page again. Default: off."}}}}}},"responses":{"200":{"description":"Markdown (text/markdown) or JSON","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","description":"format=markdown returns text/markdown; format=json returns this object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"author":{"type":["string","null"]},"date":{"type":["string","null"]},"siteName":{"type":["string","null"]},"description":{"type":["string","null"]},"contentType":{"type":"string","enum":["html","pdf","feed"]},"pageType":{"type":"string","enum":["article","index","feed","pdf"]},"items":{"type":"array","description":"Headlines (index pages) or feed items: {title, link, date?, summary?}"},"markdown":{"type":"string"},"wordCount":{"type":"number"},"links":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"href":{"type":"string"}}}},"tables":{"type":"array","items":{"type":"object","properties":{"caption":{"type":"string"},"headers":{"type":"array"},"rows":{"type":"array"}}}}}}}}},"402":{"description":"x402 payment required (USDC)","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number"},"accepts":{"type":"array"}}}}}}}}},"/v1/credits/buy":{"post":{"operationId":"buyCredits","summary":"Buy a prepaid credit bundle via x402 (default bundle 500)","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"dynamic","currency":"USD","min":"1","max":"8"},"network":"eip155:8453","asset":"USDC","note":"bundle=500: $1, bundle=5000: $8"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"bundle":{"type":"integer","enum":[500,5000]}}}}}},"parameters":[{"name":"bundle","in":"query","required":false,"schema":{"type":"integer","enum":[500,5000],"default":500},"description":""}],"responses":{"200":{"description":"Credits added; returns apiKey if none was sent"},"402":{"description":"x402 payment required (USDC)","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number"},"accepts":{"type":"array"}}}}}}}}},"/v1/read":{"get":{"operationId":"readUrl","description":"Read a web page or PDF and get its main content as clean, compact Markdown (default) or JSON. Use when a normal fetch returns an empty JavaScript shell, a cookie/consent page, raw PDF bytes, or bloated HTML full of navigation and ads. Renders JavaScript with headless Chromium when needed, accepts consent walls, and strips boilerplate. JSON adds title, author, date, links and tables. News homepages return headline lists, RSS/Atom feeds return items, mode=full returns the whole page. StackOverflow, npm and PyPI are read via their official APIs. Sites that block bots fail fast with a clear error and are not charged.","tags":["read"],"summary":"Read a URL (5 free calls/day without a key; with a key uses prepaid credits)","security":[],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"The page, PDF or RSS/Atom feed to read. Also accepted as u or link, without https://, or path style /v1/read/https://…."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["markdown","json"]},"description":"markdown returns the content as Markdown only. json wraps the same Markdown with title, author, date, word count, links, tables and metadata (meta.warning flags results that may be incomplete); there is no separate plain-text copy. Default: markdown."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["auto","article","links","full"]},"description":"article: main content only. links: list of headlines with links. full: the whole page, including non-article parts. auto picks article or links based on the page. RSS/Atom feeds always return their items. Default: auto."},{"name":"render","in":"query","required":false,"schema":{"type":"string","enum":["auto","never","always"]},"description":"Whether to load the page in headless Chromium. auto does so only when plain fetching returns too little. Default: auto."},{"name":"extract","in":"query","required":false,"schema":{"type":"string"},"description":"Returns named fields (title, author, date, price, currency, image, brand, sku, rating, availability, summary…) from JSON-LD, OpenGraph, microdata and meta tags. No LLM. Missing fields are null. In JSON as `fields`, in Markdown as front matter. Default: (none)."},{"name":"nocache","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Skips the 10-minute result cache and reads the page again. Default: off."}],"responses":{"200":{"description":"Markdown (text/markdown) or JSON","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","description":"format=markdown returns text/markdown; format=json returns this object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"author":{"type":["string","null"]},"date":{"type":["string","null"]},"siteName":{"type":["string","null"]},"description":{"type":["string","null"]},"contentType":{"type":"string","enum":["html","pdf","feed"]},"pageType":{"type":"string","enum":["article","index","feed","pdf"]},"items":{"type":"array","description":"Headlines (index pages) or feed items: {title, link, date?, summary?}"},"markdown":{"type":"string"},"wordCount":{"type":"number"},"links":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"href":{"type":"string"}}}},"tables":{"type":"array","items":{"type":"object","properties":{"caption":{"type":"string"},"headers":{"type":"array"},"rows":{"type":"array"}}}}}}}}},"402":{"description":"Free quota/credits exhausted; x402 payment accepted"}}}},"/v1/card/packs":{"get":{"operationId":"listCardPacks","summary":"Credit packs payable by card (hosted checkout at /buy)","security":[],"responses":{"200":{"description":"{ enabled, packs[] }"}}}},"/v1/card/orders":{"post":{"operationId":"createCardOrder","summary":"Create a card-payment order for a credit pack (returns exact USDC amount; pay at /buy). Issues a new key if none is sent.","security":[{"bearerApiKey":[]},{}],"parameters":[{"name":"pack","in":"query","required":false,"schema":{"type":"integer"},"description":"Pack size in calls (e.g. 7000)"}],"responses":{"201":{"description":"Order"},"503":{"description":"Card payments not configured"}}}},"/v1/card/orders/{id}":{"get":{"operationId":"getCardOrder","summary":"Card order status: pending, paid or expired","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"}}}},"/v1/search":{"get":{"operationId":"search","summary":"Web search (private SearXNG, DuckDuckGo fallback): ranked results {title,url,snippet}. Priced like one read.","security":[],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20},"description":""},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","markdown"]},"description":""}],"responses":{"200":{"description":"{ query, backend, results[] }"},"400":{"description":"Missing q (body explains usage)"},"402":{"description":"Free quota/credits exhausted; x402 payment accepted"}}}},"/v1/keys":{"post":{"operationId":"createKey","summary":"Issue an empty API key (holds prepaid credits; no free calls)","security":[],"responses":{"201":{"description":"{ apiKey }"}}}},"/v1/balance":{"get":{"operationId":"getBalance","summary":"Prepaid credits for an API key","security":[],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer ar_..."}],"responses":{"200":{"description":"Balance"}}}},"/v1/credits/bundles":{"get":{"operationId":"listBundles","summary":"Credit bundles","security":[],"responses":{"200":{"description":"Bundles"}}}}}}