{"openapi":"3.1.0","info":{"title":"Veyrly Evidence API","version":"0.1.0","description":"Validated multi-source web evidence packs for autonomous agents. One paid request returns a normalized answer with authoritative sources and validation evidence."},"servers":[{"url":"https://api.veyrly.com"}],"tags":[{"name":"search"},{"name":"research"},{"name":"evidence"},{"name":"web"},{"name":"citations"},{"name":"source-validation"},{"name":"current-information"}],"paths":{"/v1/evidence":{"post":{"operationId":"createEvidencePack","summary":"Purchase a validated multi-source Web Evidence Pack","description":"Validated multi-source web evidence packs for autonomous agents. One paid request returns a normalized answer with authoritative sources and validation evidence. Veyrly uses Exa as its current provider. It validates evidence before settlement. It does not guarantee absolute truth, exhaustive coverage, or freshness unless freshness_seconds is supplied.","tags":["search","research","evidence","web","citations","source-validation","current-information"],"security":[{"x402":[]}],"x-x402":{"protocol":"x402","version":2,"scheme":"exact","price":{"amount":"0.015","currency":"USDC","atomicAmount":"15000"},"network":{"name":"Base Mainnet","caip2":"eip155:8453"},"asset":{"symbol":"USDC","contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6},"payTo":"0x1C655df3b37C0f0545aB1910EaB038a73ecf9ffD","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","header":"PAYMENT-SIGNATURE","settlementPolicy":"authorization -> provider -> validation -> settlement -> fulfillment"},"x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.015"},"network":"eip155:8453","scheme":"exact","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x1C655df3b37C0f0545aB1910EaB038a73ecf9ffD"},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for this logical purchase. Replays never cause a second provider execution or settlement.","schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":400,"description":"Web evidence question or research query."},"freshness_seconds":{"type":"integer","minimum":60,"maximum":31536000,"description":"Optional maximum evidence age. Freshness is enforced only when requested."},"max_sources":{"type":"integer","minimum":3,"maximum":10,"default":5,"description":"Maximum number of validated sources returned."}}},"examples":{"basic":{"value":{"query":"What is the purpose of the robots.txt standard for web crawlers? Provide evidence from authoritative sources.","max_sources":5}}}}}},"responses":{"200":{"description":"Evidence validated, payment settled, and result fulfilled.","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement result.","schema":{"type":"string"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}},"X-Idempotent-Replay":{"schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","query","answer","sources","freshness","evidence","fulfilled_at","request_id"],"properties":{"status":{"const":"fulfilled"},"query":{"type":"string"},"answer":{"type":"string"},"sources":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["title","url","snippet","published_at","updated_at"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"snippet":{"type":"string"},"published_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}}},"freshness":{"type":"object","required":["required","satisfied","newest_timestamp"],"properties":{"required":{"type":"boolean"},"satisfied":{"type":"boolean"},"newest_timestamp":{"type":["string","null"],"format":"date-time"}}},"evidence":{"type":"object","required":["source_count","distinct_source_count","validated"],"properties":{"source_count":{"type":"integer","minimum":3},"distinct_source_count":{"type":"integer","minimum":1},"validated":{"const":true}}},"fulfilled_at":{"type":"string","format":"date-time"},"request_id":{"type":"string","format":"uuid"}}},"examples":{"fulfilled":{"value":{"status":"fulfilled","query":"What is the purpose of the robots.txt standard for web crawlers? Provide evidence from authoritative sources.","answer":"The Robots Exclusion Protocol lets service owners communicate crawler access preferences and helps manage crawler traffic.","sources":[{"title":"RFC 9309: Robots Exclusion Protocol","url":"https://www.rfc-editor.org/rfc/rfc9309.html","snippet":"The RFC standardizes the Robots Exclusion Protocol.","published_at":"2022-09-01T00:00:00Z","updated_at":null},{"title":"Google robots.txt documentation","url":"https://developers.google.com/search/docs/crawling-indexing/robots/intro","snippet":"robots.txt is used primarily to manage crawler traffic.","published_at":null,"updated_at":null},{"title":"Google REP specification","url":"https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec","snippet":"Google crawlers support the Robots Exclusion Protocol.","published_at":null,"updated_at":null}],"freshness":{"required":false,"satisfied":true,"newest_timestamp":"2022-09-01T00:00:00Z"},"evidence":{"source_count":3,"distinct_source_count":3,"validated":true},"fulfilled_at":"2026-09-01T21:11:48.428Z","request_id":"78390ac9-ff82-459e-a7f0-2ee63ce2553c"}}}}}},"400":{"description":"Invalid input or missing idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"402":{"description":"x402 v2 payment authorization required. Read PAYMENT-REQUIRED, create an exact EIP-3009 authorization, then retry with PAYMENT-SIGNATURE.","headers":{"PAYMENT-REQUIRED":{"required":true,"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"409":{"description":"Idempotency conflict or pending request requiring reconciliation.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"422":{"description":"Economic guard rejected the request or evidence did not pass validation. No settlement occurs after validation rejection.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}},"502":{"description":"Provider or settlement failure.","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"components":{"schemas":{"EvidenceRequest":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":400,"description":"Web evidence question or research query."},"freshness_seconds":{"type":"integer","minimum":60,"maximum":31536000,"description":"Optional maximum evidence age. Freshness is enforced only when requested."},"max_sources":{"type":"integer","minimum":3,"maximum":10,"default":5,"description":"Maximum number of validated sources returned."}}},"EvidenceResponse":{"type":"object","additionalProperties":false,"required":["status","query","answer","sources","freshness","evidence","fulfilled_at","request_id"],"properties":{"status":{"const":"fulfilled"},"query":{"type":"string"},"answer":{"type":"string"},"sources":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["title","url","snippet","published_at","updated_at"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"snippet":{"type":"string"},"published_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}}},"freshness":{"type":"object","required":["required","satisfied","newest_timestamp"],"properties":{"required":{"type":"boolean"},"satisfied":{"type":"boolean"},"newest_timestamp":{"type":["string","null"],"format":"date-time"}}},"evidence":{"type":"object","required":["source_count","distinct_source_count","validated"],"properties":{"source_count":{"type":"integer","minimum":3},"distinct_source_count":{"type":"integer","minimum":1},"validated":{"const":true}}},"fulfilled_at":{"type":"string","format":"date-time"},"request_id":{"type":"string","format":"uuid"}}},"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}}},"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 exact-payment authorization. Obtain requirements from the HTTP 402 response."}}},"externalDocs":{"description":"Agent usage guide","url":"https://api.veyrly.com/skill.md"}}