{"openapi":"3.1.0","info":{"title":"AgenticTotem Web Extractor API","description":"A payment-gated web extraction service that fetches web pages and extracts\nstructured data according to a caller-defined JSON Schema.\n\n**Pricing:** $0.01/URL in USDC (Base via x402 or Tempo via MPP).\n\n**Supported payment protocols:**\n- **x402** (default): USDC on Base (EIP-155 chain 8453) via Coinbase CDP. Send request →\n  receive 402 with payment requirements → x402-aware client signs USDC payment → retry\n  with `PAYMENT-SIGNATURE` header.\n- **MPP** (Machine Payments Protocol): USDC on Tempo via the `mppx` SDK.\n  Send request with `X-Payment-Protocol: mpp` (or let auto-detection handle it) → receive\n  402 with `WWW-Authenticate` header and RFC 7807 challenge body → pay on Tempo → retry\n  with `Authorization: Payment <credential>`. The `tempo` CLI handles this automatically.\n\nSelect protocol via the `X-Payment-Protocol` header (`x402` or `mpp`). Default: `x402`.\nNo API key or account registration required.\n","version":"1.0.0","x-guidance":"Use POST /services/web-extractor to extract structured data from web pages.\nSend a JSON body with 'urls' (array of 1-10 URLs) and 'schema' (a JSON Schema\ndescribing the data you want extracted from each page). The service costs $0.01\nper URL in USDC. Payment is handled automatically via x402 or MPP protocols —\nyour first request will receive a 402 response with payment instructions, then\nretry with the payment credential attached.\n","contact":{"name":"AgenticTotem","url":"https://agentictotem.com"}},"x-discovery":{"ownershipProofs":[]},"servers":[{"url":"https://agentictotem.com","description":"Production"}],"tags":[{"name":"web-extraction","description":"Endpoints for extracting structured data from web pages"},{"name":"x402","description":"Endpoints that accept x402 micropayment"},{"name":"mpp","description":"Endpoints that accept MPP (Machine Payments Protocol) sessions"}],"paths":{"/services/web-extractor":{"post":{"operationId":"extractWebContent","summary":"Extract structured data from web pages","description":"Fetches 1–10 web pages and extracts structured data from each page\naccording to the provided JSON Schema. Returns per-URL results with\nextracted data, status, and a summary of the batch.\n\n**Cost:** $0.01/URL in USDC (Base via x402 or Tempo via MPP).\n","tags":["web-extraction","x402","mpp"],"x-payment-info":{"protocols":["mpp"],"pricingMode":"range","minPrice":"0.010000","maxPrice":"0.100000"},"parameters":[{"name":"X-Payment-Protocol","in":"header","required":false,"schema":{"type":"string","enum":["x402","mpp"],"default":"x402"},"description":"Payment protocol to use. Defaults to \"x402\" if omitted.\n- \"x402\": USDC on Base via Coinbase CDP\n- \"mpp\": USDC on Tempo via MPP\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionRequest"},"examples":{"single-url":{"summary":"Extract article metadata from one URL","value":{"urls":["https://example.com/blog/ai-agents-2026"],"schema":{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"}},"required":["title"]}}},"multiple-urls":{"summary":"Extract product data from multiple URLs","value":{"urls":["https://shop.example.com/product/1","https://shop.example.com/product/2","https://shop.example.com/product/3"],"schema":{"type":"object","properties":{"productName":{"type":"string"},"price":{"type":"number"},"inStock":{"type":"boolean"}},"required":["productName","price"]}}}}}}},"responses":{"200":{"description":"Extraction completed successfully. Individual URLs may still have errors — check each result's `status` field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionResponse"},"examples":{"success":{"summary":"All URLs extracted successfully","value":{"results":[{"url":"https://example.com/blog/ai-agents-2026","status":"success","data":{"title":"AI Agents in 2026","author":"Jane Smith","publishedDate":"2026-03-01"}}],"summary":{"total":1,"succeeded":1,"failed":0,"price_charged":"$0.01"}}},"partial-failure":{"summary":"Some URLs failed","value":{"results":[{"url":"https://example.com/page1","status":"success","data":{"title":"Page One"}},{"url":"https://example.com/404-page","status":"fetch_error","data":null,"error":{"code":"FETCH_FAILED","message":"HTTP 404: page not found","detail":"Server returned status 404","retryable":false}}],"summary":{"total":2,"succeeded":1,"failed":1,"price_charged":"$0.02"}}}}}}},"400":{"description":"Validation error. The request body is malformed or violates constraints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"empty-urls":{"summary":"Empty urls array","value":{"error":{"code":"VALIDATION_ERROR","message":"At least 1 URL is required","detail":"urls: At least 1 URL is required","retryable":false}}},"invalid-schema":{"summary":"Invalid JSON Schema","value":{"error":{"code":"INVALID_SCHEMA","message":"Schema must have at least one property","detail":"schema.properties: Schema must have at least one property","retryable":false}}}}}}},"402":{"description":"Payment required. The response body contains payment requirements\nfor the selected protocol (x402 or MPP).\n\n**x402**: Returns payment requirements in the `PAYMENT-REQUIRED` header\nand JSON body with x402 scheme details.\n\n**MPP**: Returns a `WWW-Authenticate` header with MPP challenge parameters\nand an RFC 7807 Problem Details JSON body with a `challengeId`. The\n`tempo` CLI and `mppx` client SDK handle this automatically.\n","headers":{"WWW-Authenticate":{"description":"Present when using MPP protocol. Contains the MPP payment challenge\nthat clients use to construct a payment credential.\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/X402PaymentRequired"},{"$ref":"#/components/schemas/MppPaymentRequired"}]},"example":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base","maxAmountRequired":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xYourAgenticTotemPaymentAddress","maxTimeoutSeconds":300}]}}}}}}}},"components":{"schemas":{"ExtractionRequest":{"type":"object","required":["urls","schema"],"properties":{"urls":{"type":"array","description":"List of URLs to fetch and extract data from. Minimum 1, maximum 10.","minItems":1,"maxItems":10,"items":{"type":"string","format":"uri"},"examples":[["https://example.com/article"]]},"schema":{"type":"object","description":"A JSON Schema object describing the desired structure of extracted data.\nThe service will attempt to extract data from each URL conforming to this schema.\nMust have `type: \"object\"` and at least one property.\n","examples":[{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"}},"required":["title"]}]}}},"ExtractionResponse":{"type":"object","required":["results","summary"],"properties":{"results":{"type":"array","description":"Per-URL extraction results.","items":{"$ref":"#/components/schemas/ExtractionResult"}},"summary":{"$ref":"#/components/schemas/ExtractionSummary"}}},"ExtractionResult":{"type":"object","required":["url","status"],"properties":{"url":{"type":"string","format":"uri","description":"The URL that was processed."},"status":{"type":"string","enum":["success","fetch_error","extraction_error"],"description":"Whether extraction succeeded for this URL."},"data":{"description":"The extracted data conforming to the request schema.\nPresent when status is \"success\", absent or null on error.\n","oneOf":[{"type":"object"},{"type":"null"}]},"error":{"description":"Error object describing why extraction failed for this URL.\nPresent when status is \"fetch_error\" or \"extraction_error\", absent or null on success.\n","oneOf":[{"$ref":"#/components/schemas/AgenticError"},{"type":"null"}]}}},"ExtractionSummary":{"type":"object","required":["total","succeeded","failed","price_charged"],"properties":{"total":{"type":"integer","description":"Total number of URLs in the request."},"succeeded":{"type":"integer","description":"Number of URLs successfully extracted."},"failed":{"type":"integer","description":"Number of URLs that failed extraction."},"price_charged":{"type":"string","description":"Total price charged for this request (e.g., \"$0.05\")."}}},"AgenticError":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","description":"Error type identifier.","enum":["VALIDATION_ERROR","INVALID_SCHEMA","INVALID_URL","URL_LIMIT_EXCEEDED","FETCH_FAILED","FETCH_TIMEOUT","CONTENT_TOO_LARGE","EXTRACTION_FAILED","EXTRACTION_TIMEOUT","INTERNAL_ERROR"]},"message":{"type":"string","description":"Human-readable error message."},"detail":{"type":"string","description":"Additional details about the error."},"url":{"type":"string","format":"uri","description":"The URL that caused the error (present in per-URL errors)."},"retryable":{"type":"boolean","description":"Whether the client should retry this request."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/AgenticError"}}},"X402PaymentRequired":{"type":"object","description":"x402 payment requirements returned when no payment is attached to the request.\nAn x402-aware HTTP client parses this, signs a USDC payment, and retries\nthe request with the `PAYMENT-SIGNATURE` header.\n","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","description":"x402 protocol version. Currently 2.","enum":[2]},"accepts":{"type":"array","description":"List of accepted payment schemes.","items":{"type":"object","required":["scheme","network","maxAmountRequired","asset","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"type":"string","description":"Payment scheme identifier.","enum":["exact"]},"network":{"type":"string","description":"Blockchain network for payment.","enum":["base"]},"maxAmountRequired":{"type":"string","description":"Maximum payment amount in atomic units of the asset.\nFor USDC (6 decimals): \"10000\" = $0.01, \"100000\" = $0.10.\nActual amount depends on the number of URLs in the request.\n"},"asset":{"type":"string","description":"Contract address of the payment token (USDC on Base)."},"payTo":{"type":"string","description":"Address to send payment to."},"maxTimeoutSeconds":{"type":"integer","description":"Maximum time (seconds) before the payment authorization expires."}}}}}},"MppPaymentRequired":{"type":"object","description":"RFC 7807 Problem Details response returned by the `mppx` SDK when\nusing MPP protocol without a valid payment credential. The response\nalso includes a `WWW-Authenticate` header with the payment challenge.\n\nThe `tempo` CLI and `mppx` client SDK handle this flow automatically:\nparse challenge → pay on Tempo → retry with `Authorization: Payment <credential>`.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"Problem type URI identifying this as an MPP payment challenge.","example":"https://paymentauth.org/problems/payment-required"},"title":{"type":"string","example":"Payment Required"},"status":{"type":"integer","example":402},"detail":{"type":"string","description":"Human-readable explanation."},"challengeId":{"type":"string","description":"Opaque challenge identifier used by the client to construct a payment credential."}}}},"x-x402":{"description":"This API uses the x402 protocol for payment. No API keys or accounts required.\n","payment":{"protocol":"x402","version":1,"pricePerUrl":"$0.01","currency":"USDC","network":"Base (EIP-155 chain 8453)","contractAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","flow":"1. Client sends POST /services/web-extractor without payment\n2. Server returns 402 with payment requirements in response body\n3. Client's x402 middleware signs a USDC payment authorization\n4. Client retries the request with PAYMENT-SIGNATURE header\n5. Server verifies payment and processes the extraction\n6. Server returns 200 with extraction results\n"}}}}