fresh402_extract
Extract readable text, metadata, headings, public links and embedded JSON-LD from one public HTTPS document. Use to read static HTML, JSON or plain text; no watch or prior registration is needed. Optional feed_mode:entries projects bounded RSS2/Atom IDs, declared links, timestamps, content fingerprints and indexed source evidence; omit for original XML-as-text behavior. No feed crawling or background subscription. Optional CSS scope, noise exclusions and exact JSON Pointer selection via json_pointer, or an ordered projection of up to8 fields via json_pointers (mutually exclusive; JSON only, any missing field returns422). One fetch/JSON parse with aggregate work/output limits. Omit json_pointer to retain full-document extraction. max_chars defaults to 20000 and limits returned text, not fetch size. Does not render JavaScript, crawl links or compare versions. $0.010 USDC per call on Base mainnet (eip155:8453), requiring an x402-capable MCP payment client and funded native-USDC payer. An ordinary MCP client receives a payment challenge. Alternatively use prepaid credits through REST or this MCP tool: X-Fresh402-API-Key in HTTP, with params._meta["fresh402/prepaid"] containing idempotency_key, tariff_version and max_credits. When root mpp_payments.enabled is true, native MPP EVM charge is another option at the same USDC price: use an authorized Base EIP-712 signer and official mppx client, org.paymentauth/credential metadata and a persisted private recovery token. MPP receipt: org.paymentauth/receipt; see docs/MPP.md. Never combine MPP, prepaid and x402. Discover packages at /v2/prepaid/plans; see docs/AGENT_PREPAID.md for browserless wallet enrollment, bounded early credits and recovery. Optional Circle Gateway x402 is available only when root circle_gateway.enabled is true. Use the GatewayWalletBatched quote, a funded Base Gateway EOA and a persisted private recovery token. Pending batches return 409; replay the original proof/input/token after 60 seconds. Results require Gateway confirmed/completed evidence; never mix providers. No Circle prepaid funding. See docs/CIRCLE_GATEWAY.md. Optional free evaluation: inspect GET /v3/agent-trial for the CAPTCHA-free machine trial (unfunded EOA ownership signing required). Web tools may also use the separate human trial at /v2/trial. Only enabled, eligible allowances authorize free execution; shared capacity can return 429 earlier. Send X-Fresh402-Trial-Key and a distinct persisted Idempotency-Key per logical REST or MCP call. Reuse the same tool/input/key for retained recovery. Never mix trial and payment/prepaid credentials. Exhaustion never authorizes a charge; ordinary requests without trial credentials retain the paid challenge.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Required absolute public HTTPS document URL, at most 4096 characters, e.g. 'https://example.com/docs'. Only port 443; no embedded credentials, private/local targets or authenticated pages. Fresh402's own service URLs, including its discovery /openapi.json, cannot be targets; choose an external public document. HTML, JSON and plain text are supported; JavaScript is not executed. DNS, redirect and size limits also apply. | |
| selector | No | Optional HTML CSS scope, 1-256 characters, e.g. 'article'. If omitted, choose main, then article, then body, then the document. Explicit scope must match (otherwise 422). Built-in noise and ignore_selectors are removed. Not supported for JSON/plain text. | |
| feed_mode | No | Optional RSS2/Atom projection: 'entries'. Omit for unchanged XML-as-text extraction and existing hashes. Accepts XML/+xml/text/plain with an RSS2 root or namespaced Atom feed; no RSS1/RDF, HTML repair, DTD or external entity/content fetching. Cannot combine with CSS/JSON selection or exclusions. Limits:262144 UTF-8 source bytes,4096 XML elements,depth32,100 entries,16384 characters/field,131072 projected bytes; excess fails explicitly. Returns feed identity, inert declared links, entry IDs/timestamps/content fingerprints and indexed source evidence. Identical duplicate entries deduplicate; conflicting IDs fail422. Feed text/hash cover the canonical projection; max_chars clips text and omits structured feed when clipped. Existing registration/watch semantics remain unchanged. | |
| max_chars | No | Optional integer limit on returned normalized text: 100-50000 characters, default 20000. Does not raise fetch/parser limits; the hash covers full normalized text before truncation. If JSON text is truncated, parsed data is omitted (data:null, data_omitted:true). | |
| json_pointer | No | Optional exact RFC 6901 JSON Pointer, at most 256 characters, e.g. '/product/price' or '/items/0/name'. JSON documents only; '~0' means '~' and '~1' means '/'. Empty string selects the whole document. Omit to extract the entire normalized document. Selection runs after ignore_json_paths; a missing or excluded target returns 422. Array indices are zero-based canonical integers; '*' is a literal key, not a wildcard. Returned text/data/hash cover the selected value; max_chars and data_omitted still apply. | |
| include_links | No | Optional boolean, default true. Include bounded public links extracted from HTML. False returns an empty links array without changing normalized text or its hash. Does not crawl linked pages; JSON/plain text do not provide HTML links. | |
| json_pointers | No | Optional ordered1-8 unique exact JSON Pointers; mutually exclusive with json_pointer, JSON only. One fetch and JSON parse; exclusions run first. Any missing/excluded field fails the whole operation with422; null is a valid value. Returns data:[{pointer,value},...] and canonical aggregate text/hash. max_chars clips the aggregate; clipped data is omitted. Combined projection limited to200000 UTF-8 bytes and20000 nodes. Example:['/product/price','/product/stock']. | |
| ignore_selectors | No | Optional array of up to 20 CSS selectors (each 1-256 characters) to remove from HTML in addition to built-in noise filtering. Default: no extra exclusions ([]). HTML only; use ignore_json_paths for JSON. Example: ['.timestamp', '.ad']. | |
| ignore_json_paths | No | Optional array of up to 20 JSON Pointer-style paths to remove before JSON normalization and hashing. Each must start with '/' and be 1-256 characters; supports '*' segments. Default: [] (no exclusions). JSON only. Example: ['/updated_at', '/items/*/request_id']. | |
| include_structured_data | No | Optional boolean, default true. Include embedded JSON-LD extracted from HTML in structured_data. False returns an empty structured_data array. This does not control the parsed data field for a JSON document, and does not fetch external linked data. |