{"openapi":"3.1.0","x-discovery":{"ownershipProofs":["0xb866dD8C8401438Efb29b538ec4df11b6b407Ce6"]},"info":{"title":"AgentRead API","version":"0.1.0","description":"Clean web content for AI agents, paid per request via x402. Paid endpoints return HTTP 402 with x402 v2 payment requirements; retry with a `PAYMENT-SIGNATURE` header produced by an x402 client (e.g. @x402/fetch). Only successful extractions are settled.","contact":{"name":"AgentRead","email":"omarhatef@hotmail.com","url":"https://github.com/omarhassanatef/agentread/issues"},"license":{"name":"MIT","url":"https://github.com/omarhassanatef/agentread/blob/main/LICENSE"},"x-guidance":"Use AgentRead to read a public web page as clean Markdown instead of raw HTML. Call POST /v1/inspect (free) first to check the URL is reachable and extractable. Then call POST /v1/extract for Markdown, or POST /v1/extract/structured when you also need metadata, headings and links separately. Bodies are JSON: {\"url\": \"https://…\", \"maxCharacters\"?: number, \"includeLinks\"?: boolean}. Paid calls follow x402 v2: an unpaid call returns 402 with a PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE. Failed extractions (4xx/5xx) are not charged. JavaScript is not executed; pages that need it return javascript_required."},"servers":[{"url":"https://agentread.omar-cv.workers.dev"}],"paths":{"/health":{"get":{"summary":"Health check","security":[],"responses":{"200":{"description":"Service is up."}}}},"/":{"get":{"summary":"Service discovery document (operations, prices, limits)","security":[],"responses":{"200":{"description":"Discovery JSON."}}}},"/v1/inspect":{"post":{"summary":"Inspect a URL (free)","operationId":"inspect_url","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InspectInput"}}}},"responses":{"200":{"description":"Inspection result. Upstream failures are reported in the body (reachable=false, limitation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InspectResult"}}}},"400":{"description":"Invalid input or blocked destination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/extract":{"post":{"summary":"Extract clean Markdown (paid)","operationId":"extract_url","description":"Costs $0.003 in USDC on Base (eip155:8453) via x402 v2 `exact` scheme.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{"version":2,"scheme":"exact","network":"eip155:8453","asset":"USDC"}}]},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 PaymentPayload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractInput"}}}},"responses":{"200":{"description":"Extraction succeeded and payment was settled. The `PAYMENT-RESPONSE` header carries the base64 settlement receipt.","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded x402 SettleResponse."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResult"}}}},"400":{"description":"Invalid input or blocked destination (returned before any payment is requested).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required, invalid/expired/replayed payment, or settlement failure. The `PAYMENT-REQUIRED` header carries the base64 x402 PaymentRequired object (accepts[], resource).","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 PaymentRequired."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Page could not be extracted (unsupported content, too large, empty, requires JavaScript, too many redirects, unknown host). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream page or DNS error, or facilitator error. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Payments not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Upstream page timed out. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/extract/structured":{"post":{"summary":"Structured extraction (paid)","operationId":"extract_url_structured","description":"Costs $0.005 in USDC on Base (eip155:8453) via x402 v2 `exact` scheme.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{"version":2,"scheme":"exact","network":"eip155:8453","asset":"USDC"}}]},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 PaymentPayload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractInput"}}}},"responses":{"200":{"description":"Extraction succeeded and payment was settled. The `PAYMENT-RESPONSE` header carries the base64 settlement receipt.","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded x402 SettleResponse."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredResult"}}}},"400":{"description":"Invalid input or blocked destination (returned before any payment is requested).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required, invalid/expired/replayed payment, or settlement failure. The `PAYMENT-REQUIRED` header carries the base64 x402 PaymentRequired object (accepts[], resource).","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 PaymentRequired."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request body is not JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Page could not be extracted (unsupported content, too large, empty, requires JavaScript, too many redirects, unknown host). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream page or DNS error, or facilitator error. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Payments not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Upstream page timed out. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"summary":"MCP Streamable HTTP endpoint (stateless, JSON responses)","security":[],"description":"JSON-RPC 2.0 per the MCP Streamable HTTP transport. Tools: inspect_url, extract_url, extract_url_structured. Paid tools return an x402 PaymentRequired tool result (isError=true, structuredContent) and accept payment in `params._meta[\"x402/payment\"]`.","responses":{"200":{"description":"JSON-RPC response."}}}}},"components":{"schemas":{"InspectInput":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"Absolute public http:// or https:// URL. Default ports only; no credentials; no IP literals."}},"required":["url"],"additionalProperties":false},"ExtractInput":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"Absolute public http:// or https:// URL. Default ports only; no credentials; no IP literals."},"maxCharacters":{"type":"integer","minimum":100,"maximum":100000,"description":"Maximum Markdown characters to return (default 20000, max 100000)."},"includeLinks":{"type":"boolean","description":"Keep hyperlinks and images in the Markdown (default true). When false, link text is kept as plain text."}},"required":["url"],"additionalProperties":false},"InspectResult":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0"]},"operation":{"type":"string","enum":["inspect_url"]},"requestedUrl":{"type":"string"},"normalizedUrl":{"type":"string"},"hostname":{"type":"string"},"reachable":{"type":"boolean"},"statusCode":{"type":"integer","nullable":true},"finalUrl":{"type":"string","nullable":true},"redirects":{"type":"integer"},"contentType":{"type":"string","nullable":true},"contentLength":{"type":"integer","nullable":true},"isHtml":{"type":"boolean"},"title":{"type":"string","nullable":true},"mayRequireJavaScript":{"type":"boolean"},"extractionSupported":{"type":"boolean"},"limitation":{"type":"string","nullable":true}},"required":["schemaVersion","operation","requestedUrl","normalizedUrl","hostname","reachable","statusCode","finalUrl","redirects","contentType","contentLength","isHtml","title","mayRequireJavaScript","extractionSupported","limitation"],"additionalProperties":false},"ExtractResult":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0"]},"operation":{"type":"string","enum":["extract_url"]},"requestedUrl":{"type":"string"},"finalUrl":{"type":"string"},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"markdown":{"type":"string"},"headings":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"string"}},"required":["level","text"],"additionalProperties":false}},"truncated":{"type":"boolean"},"extraction":{"type":"object","properties":{"method":{"type":"string","enum":["readability","main-content-fallback","body-fallback","plain-text","lite"]},"statusCode":{"type":"integer"},"contentType":{"type":"string","nullable":true},"charset":{"type":"string"},"redirects":{"type":"integer"},"bytesFetched":{"type":"integer"},"characters":{"type":"integer","description":"Length of the returned Markdown."},"totalCharacters":{"type":"integer","description":"Length of the Markdown before truncation."},"words":{"type":"integer","description":"Word count of the returned Markdown."},"warnings":{"type":"array","items":{"type":"string"}},"durationMs":{"type":"number"}},"required":["method","statusCode","contentType","charset","redirects","bytesFetched","characters","totalCharacters","words","warnings","durationMs"],"additionalProperties":false}},"required":["schemaVersion","operation","requestedUrl","finalUrl","title","description","markdown","headings","truncated","extraction"],"additionalProperties":false},"StructuredResult":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0"]},"operation":{"type":"string","enum":["extract_url_structured"]},"requestedUrl":{"type":"string"},"finalUrl":{"type":"string"},"metadata":{"type":"object","properties":{"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"canonicalUrl":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"siteName":{"type":"string","nullable":true},"byline":{"type":"string","nullable":true},"publishedTime":{"type":"string","nullable":true}},"required":["title","description","canonicalUrl","language","siteName","byline","publishedTime"],"additionalProperties":false},"markdown":{"type":"string"},"headings":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"string"}},"required":["level","text"],"additionalProperties":false}},"headingsTruncated":{"type":"boolean"},"links":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string"}},"required":["text","url"],"additionalProperties":false}},"linksTruncated":{"type":"boolean"},"truncated":{"type":"boolean"},"extraction":{"type":"object","properties":{"method":{"type":"string","enum":["readability","main-content-fallback","body-fallback","plain-text","lite"]},"statusCode":{"type":"integer"},"contentType":{"type":"string","nullable":true},"charset":{"type":"string"},"redirects":{"type":"integer"},"bytesFetched":{"type":"integer"},"characters":{"type":"integer","description":"Length of the returned Markdown."},"totalCharacters":{"type":"integer","description":"Length of the Markdown before truncation."},"words":{"type":"integer","description":"Word count of the returned Markdown."},"warnings":{"type":"array","items":{"type":"string"}},"durationMs":{"type":"number"}},"required":["method","statusCode","contentType","charset","redirects","bytesFetched","characters","totalCharacters","words","warnings","durationMs"],"additionalProperties":false}},"required":["schemaVersion","operation","requestedUrl","finalUrl","metadata","markdown","headings","headingsTruncated","links","linksTruncated","truncated","extraction"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","invalid_url","blocked_destination","request_too_large","unsupported_media_type","host_not_found","dns_resolution_failed","upstream_http_error","upstream_unreachable","upstream_timeout","too_many_redirects","unsupported_content_type","content_too_large","empty_content","javascript_required","payment_invalid","rate_limited","not_found","method_not_allowed","payments_unavailable","internal_error"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"PaymentRequired":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["payment_required","payment_settlement_failed"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}