{"openapi":"3.1.0","info":{"title":"FreshProof HTTP API","version":"1.1.0","description":"Paid machine-to-machine public URL observations with timestamped SHA-256 response-body fingerprints. POST /observe costs $0.005 USDC per call on Base via x402 v2. The price is the same for shared_cache and fresh_fetch results. A fresh_fetch means FreshProof performed a new public-network HTTP request at the recorded time. The destination itself may serve content from its own CDN, proxy, or cache."},"servers":[{"url":"https://freshproof-http.ricardobessellp-11d.workers.dev","description":"FreshProof production HTTP x402 endpoint"}],"tags":[{"name":"System","description":"Free service health and discovery endpoints."},{"name":"Observation","description":"Paid public URL observation."},{"name":"Proof","description":"Free proof retrieval and verification."}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health Check","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service is operating normally.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"}},"required":["status"],"additionalProperties":false}}}}}}},"/openapi.json":{"get":{"tags":["System"],"summary":"OpenAPI Specification","operationId":"getOpenApiSpecification","security":[],"responses":{"200":{"description":"FreshProof production HTTP OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/proof/{proofId}":{"get":{"tags":["Proof"],"summary":"Get a FreshProof Receipt","operationId":"getProof","security":[],"parameters":[{"name":"proofId","in":"path","required":true,"schema":{"type":"string","pattern":"^fp1_[a-f0-9]{64}$"}}],"responses":{"200":{"description":"Stored proof receipt with deterministic integrity result."},"400":{"description":"Invalid proof identifier."},"404":{"description":"Proof not found."}}}},"/verify":{"post":{"tags":["Proof"],"summary":"Verify a FreshProof Receipt","operationId":"verifyProof","description":"Free deterministic integrity verification and optional declarative policy evaluation. No new public-network request is made.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proof_id":{"type":"string","pattern":"^fp1_[a-f0-9]{64}$"},"policy":{"$ref":"#/components/schemas/VerificationPolicy"}},"required":["proof_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Proof integrity and policy result."},"400":{"description":"Invalid proof_id or policy."},"404":{"description":"Proof not found."}}}},"/observe":{"post":{"tags":["Observation"],"summary":"Observe a Public URL","operationId":"observeUrl","description":"Purchases one FreshProof observation for $0.005 USDC on Base using x402 v2 exact payment. An unpaid request returns HTTP 402 with PAYMENT-REQUIRED. After payment authorization, retry the same request with PAYMENT-SIGNATURE. A successful request returns the observation and PAYMENT-RESPONSE. max_age=0 forces a new public-network HTTP request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTP or HTTPS URL to observe.","example":"https://example.com"},"max_age":{"type":"integer","minimum":0,"default":300,"description":"Maximum acceptable observation age in seconds. Set to 0 to force a fresh public-network request.","example":0}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Paid observation completed successfully.","headers":{"PAYMENT-RESPONSE":{"description":"x402 settlement confirmation.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservationResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment is required or payment authorization was rejected.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment challenge.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","example":"no-store"}}}},"413":{"description":"Observed response exceeded the configured body-size limit."},"422":{"description":"URL rejected by SSRF or public-network safety validation."},"502":{"description":"Public target fetch failed."},"504":{"description":"Public target fetch timed out."}},"x-freshproof-x402":{"protocol":"x402","version":2,"scheme":"exact","network":"eip155:8453","network_name":"Base","price":"$0.005","amount":"5000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","asset_name":"USDC","asset_decimals":6,"pay_to":"0x00b985fAC13F6d42690d8c84E0cC956c4A3C57AB","facilitator":"https://facilitator.payai.network","challenge_header":"PAYMENT-REQUIRED","payment_header":"PAYMENT-SIGNATURE","settlement_header":"PAYMENT-RESPONSE"}}}},"components":{"schemas":{"ObservationResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"final_url":{"type":"string","format":"uri"},"observed_at":{"type":"string","format":"date-time"},"age_seconds":{"type":"integer","minimum":0},"status":{"type":"integer","minimum":100,"maximum":599},"content_hash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content_length":{"type":"integer","minimum":0},"etag":{"type":["string","null"]},"last_modified":{"type":["string","null"]},"fetch_duration_ms":{"type":"integer","minimum":0},"proof_id":{"type":"string","pattern":"^fp1_[a-f0-9]{64}$"},"receipt_hash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"source":{"type":"string","enum":["shared_cache","fresh_fetch"]}},"required":["url","final_url","observed_at","age_seconds","status","content_hash","content_length","etag","last_modified","fetch_duration_ms","source","proof_id","receipt_hash"],"additionalProperties":false},"VerificationPolicy":{"type":"object","properties":{"max_age_seconds":{"type":"integer","minimum":0},"status_in":{"type":"array","minItems":1,"items":{"type":"integer","minimum":100,"maximum":599}},"content_hash_equals":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"final_host_equals":{"type":"string","minLength":1},"original_host_equals":{"type":"string","minLength":1},"require_same_origin_redirect":{"type":"boolean"},"changed_since_content_hash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error"]}}},"x-freshproof":{"service_type":"public-web-observation","payment":{"protocol":"x402","version":2,"scheme":"exact","network":"eip155:8453","network_name":"Base","price":"$0.005","amount":"5000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","asset_name":"USDC","asset_decimals":6,"pay_to":"0x00b985fAC13F6d42690d8c84E0cC956c4A3C57AB","facilitator":"https://facilitator.payai.network","challenge_header":"PAYMENT-REQUIRED","payment_header":"PAYMENT-SIGNATURE","settlement_header":"PAYMENT-RESPONSE"},"semantics":{"fresh_fetch":"FreshProof performed a new public-network HTTP request at the recorded time. The destination itself may serve content from its own CDN, proxy, or cache.","shared_cache":"FreshProof returned a previously stored observation whose age satisfied max_age."}}}