{"openapi":"3.1.0","info":{"title":"ProofFetch Agent API","version":"0.2.0","description":"Evidence-bearing public web extraction with a free preflight and Stripe MPP paid fulfillment."},"servers":[{"url":"https://proof-fetch-agent-api.neoaethel.workers.dev"}],"x-service-info":{"categories":["web-data","agent-security","research"],"docs":{"llms":"https://proof-fetch-agent-api.neoaethel.workers.dev/llms.txt","offer":"https://proof-fetch-agent-api.neoaethel.workers.dev/offer","quickstart":"https://proof-fetch-agent-api.neoaethel.workers.dev/connect"},"status":"available"},"paths":{"/v1/preflight":{"get":{"operationId":"proofFetchPreflightGet","summary":"Same free preflight as POST, for browsers and simple clients.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri","maxLength":2048}},{"name":"maxChars","in":"query","required":false,"schema":{"type":"integer","minimum":1000,"maximum":50000,"default":30000}}],"responses":{"200":{"description":"Fetch and extraction preflight. Paragraph content is withheld."},"400":{"description":"Invalid or forbidden URL.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"429":{"description":"Free preflight rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}}}},"post":{"operationId":"proofFetchPreflight","summary":"Inspect a public URL without receiving its extracted text.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTP(S) document URL. No credentials, private networks, authenticated pages or browser rendering.","examples":["https://example.com/"]},"maxChars":{"type":"integer","minimum":1000,"maximum":50000,"default":30000,"description":"Maximum normalized characters to extract. Free preflight returns metadata only, never the extracted text.","examples":[30000]}}}}}},"responses":{"200":{"description":"Fetch and extraction preflight. Paragraph content is withheld."},"400":{"description":"Invalid or forbidden URL, or malformed request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"413":{"description":"Request body or upstream page too large (request_too_large, response_too_large).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"415":{"description":"The page uses an unsupported content type (content_type_unsupported).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"422":{"description":"The public resource could not be fetched or extracted (for example upstream_http_404).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"429":{"description":"Free preflight rate limit exceeded (free_rate_limit_exceeded).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"502":{"description":"Upstream fetch failed (upstream_timeout, upstream_unreachable, redirect_location_missing).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}}}}},"/v1/evidence":{"post":{"operationId":"proofFetchEvidence","summary":"Buy cited web evidence for fifty cents.","description":"The upstream resource is fetched and extracted successfully before the server issues a payment challenge. Alternatively send Authorization: Bearer <ProofFetch key> to use one prepaid credit instead of an MPP payment; 401 credit_key_invalid or 402 credits_exhausted if the key cannot pay.","x-payment-info":{"offers":[{"amount":"0.50","currency":"usd","decimals":2,"intent":"charge","method":"stripe","description":"Fetches a public web resource and returns paragraph-addressable content, SHA-256 integrity receipts, provenance metadata, and transparent prompt-injection indicators."}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","idempotencyKey"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTP(S) document URL. No credentials, private networks, authenticated pages or browser rendering.","examples":["https://example.com/"]},"maxChars":{"type":"integer","minimum":1000,"maximum":50000,"default":30000,"description":"Maximum normalized characters to extract. Free preflight returns metadata only, never the extracted text.","examples":[30000]},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{22,128}$","description":"High-entropy caller-generated retry and recovery key."}}}}}},"responses":{"200":{"description":"Paid cited evidence with Payment-Receipt header."},"400":{"description":"Invalid or forbidden URL, malformed request, or invalid idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"402":{"description":"Stripe MPP payment challenge."},"409":{"description":"idempotency_key_conflict, idempotency_credential_conflict, or fulfillment_in_progress (retry after the Retry-After header, 120 seconds).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"413":{"description":"Request body or upstream page too large (request_too_large, response_too_large); no payment challenge was issued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"415":{"description":"The page uses an unsupported content type (content_type_unsupported); no payment challenge was issued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"422":{"description":"The public resource could not be extracted; no payment challenge was issued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"429":{"description":"Unpaid request rate limit exceeded (free_rate_limit_exceeded). Requests carrying a payment credential are not limited.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"500":{"description":"Fulfillment failed after payment was attempted (evidence_fulfillment_failed). Retry the identical request with its original idempotency key and payment credential; do not create a new key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"502":{"description":"Upstream fetch failed (upstream_timeout, upstream_unreachable, redirect_location_missing); no payment challenge was issued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}},"503":{"description":"Paid fulfillment has not launched.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Plain-language explanation and next step."},"example":{"type":"object","description":"A valid request body, on input errors."},"docs":{"type":"string"}}}}}}}}},"/v1/support":{"post":{"operationId":"proofFetchOpenSupportCase","summary":"Open a privacy-preserving technical or payment support case.","description":"Returns a one-time access token. Save it; the service stores only its SHA-256 hash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":20,"maxLength":1200,"description":"Non-sensitive payment or technical issue. Do not include credentials, payment credentials, email addresses, or phone numbers."},"requestSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contentSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"paymentReference":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,128}$"}}}}}},"responses":{"201":{"description":"Support case opened; response includes case ID and access token."},"400":{"description":"Invalid, oversize, or sensitive-data-containing request."},"429":{"description":"Support intake rate limit exceeded."}}}},"/v1/credits":{"get":{"operationId":"proofFetchCredits","summary":"Remaining prepaid extraction credits for a ProofFetch key.","security":[{"prepaidKey":[]}],"responses":{"200":{"description":"keyPrefix, creditsTotal and creditsRemaining."},"401":{"description":"Missing or invalid key (credit_key_invalid)."}}}}},"components":{"securitySchemes":{"prepaidKey":{"type":"http","scheme":"bearer","description":"ProofFetch key bought with a card (10 extractions for $5.00) at https://proof-fetch-agent-api.neoaethel.workers.dev/#buy."}}}}