{"openapi":"3.1.0","info":{"title":"Evidence for Agents API","version":"1.0.0","description":"Public-source verification. Evidence and machine interpretation remain distinct. x402 v2 exact USDC payment. No customer API key or account required."},"servers":[{"url":"https://evidenceforagents.com"}],"paths":{"/api/v1/verify":{"post":{"operationId":"verify","summary":"Verify a claim, question, subject or URL","description":"At least one of claim, question, subject or url is required. Do not provide both claim and question. Subject-only requests ask whether it is currently operating or available. URL-only requests assess verifiable information on that URL. Live research is synchronous (up to 180 seconds); 202 indicates in-progress/recovery state, not a background job queue.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"description":"Random UUID. Treat as secret recovery credential. Reuse for exactly the same request, including a paid retry."},{"in":"header","name":"PAYMENT-SIGNATURE","schema":{"type":"string","maxLength":12000},"description":"x402 v2 base64 payment payload; omit for the 402 challenge"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyInput"},"example":{"claim":"Does this company currently offer the service?","url":"https://example.com","tier":"standard"}}}},"responses":{"200":{"description":"Completed Evidence Pack; keep access.access_token secret.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement receipt","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EvidencePack"},{"type":"object","properties":{"access":{"$ref":"#/components/schemas/Access"},"payment":{"type":"object","additionalProperties":true}}}]}}}},"202":{"description":"Processing or reconciling settlement. Poll with bearer token; do not pay again.","headers":{"Retry-After":{"schema":{"type":"string","example":"5"}}},"content":{"application/json":{"schema":{"type":"object","required":["request_id","state","access"],"properties":{"request_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["processing","settling"]},"access":{"$ref":"#/components/schemas/Access"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsafe URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 v2 requirement, or invalid payment. Decode PAYMENT-REQUIRED; sign exact USDC authorization and retry the same JSON and Idempotency-Key with PAYMENT-SIGNATURE.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired object"}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"const":2},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"const":"application/json"}}},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"const":"exact"},"network":{"type":"string","enum":["eip155:8453","eip155:84532"]},"asset":{"type":"string"},"amount":{"type":"string","pattern":"^[0-9]+$"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"error":{"type":"object"}}}}}},"404":{"description":"Missing result or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict or reused payment nonce","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 12 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry the SAME key before attempting payment again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Research failed or unsettled payment expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service not configured or storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"getRequest","summary":"Retrieve a private pack or recover an interrupted settlement","security":[{"ResultToken":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Completed Evidence Pack; keep access.access_token secret.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement receipt","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EvidencePack"},{"type":"object","properties":{"access":{"$ref":"#/components/schemas/Access"},"payment":{"type":"object","additionalProperties":true}}}]}}}},"202":{"description":"Processing or reconciling settlement. Poll with bearer token; do not pay again.","headers":{"Retry-After":{"schema":{"type":"string","example":"5"}}},"content":{"application/json":{"schema":{"type":"object","required":["request_id","state","access"],"properties":{"request_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["processing","settling"]},"access":{"$ref":"#/components/schemas/Access"},"message":{"type":"string"}}}}}},"404":{"description":"Missing result or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected failure; retry the SAME key before attempting payment again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Research failed or unsettled payment expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/health":{"get":{"operationId":"health","summary":"Liveness and configuration readiness","parameters":[{"in":"query","name":"ready","schema":{"type":"string","enum":["1"]},"description":"Also test storage; HTTP 503 if not ready. Does not probe paid providers."}],"responses":{"200":{"description":"Service liveness and readiness state","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"ready":{"type":"boolean"},"mode":{"type":"string"},"readiness_scope":{"type":"string"}}}}}},"503":{"description":"Service not configured or storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","summary":"Current prices, coverage, payment network and availability","responses":{"200":{"description":"Machine-readable price catalog","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"const":"USD"},"payment_asset":{"const":"USDC"},"protocol":{"const":"x402"},"x402_version":{"const":2},"network":{"type":"string"},"mode":{"type":"string"},"available":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"usd":{"type":"string"},"sources":{"type":"integer"},"queries":{"type":"integer"}}}}}}}}}}}}},"components":{"securitySchemes":{"ResultToken":{"type":"http","scheme":"bearer","description":"access.access_token from your POST response"}},"schemas":{"VerifyInput":{"type":"object","properties":{"subject":{"type":"string","minLength":2,"maxLength":500},"claim":{"type":"string","minLength":5,"maxLength":2000},"question":{"type":"string","minLength":5,"maxLength":2000},"url":{"type":"string","format":"uri","maxLength":2048},"context":{"type":"string","maxLength":3000},"tier":{"type":"string","enum":["quick","standard","deep"],"default":"standard"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"EvidencePack":{"type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"request_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"claim":{"type":"string"},"status":{"type":"string","enum":["supported","contradicted","mixed","insufficient_evidence"]},"summary":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"confidence_kind":{"type":"string","const":"heuristic_evidence_strength_not_probability"},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"publisher":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"]},"supports":{"type":["boolean","null"]},"stance":{"type":"string","enum":["supports","contradicts","mixed","context"]},"evidence_kind":{"type":"string","enum":["page_text","search_excerpt"]},"content_sha256":{"type":"string","minLength":64,"maxLength":64}},"required":["id","url","title","publisher","retrieved_at","published_at","supports","stance","evidence_kind","content_sha256"],"additionalProperties":false}},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source_id":{"type":"string"},"statement":{"type":"string","minLength":1,"maxLength":1500},"quote":{"type":"string","minLength":1,"maxLength":800},"relation":{"type":"string","enum":["supports","contradicts","context"]}},"required":["id","source_id","statement","quote","relation"],"additionalProperties":false}},"conclusion":{"type":"object","properties":{"text":{"type":"string"},"fact_ids":{"type":"array","items":{"type":"string"}},"interpretation":{"type":"boolean","const":true}},"required":["text","fact_ids","interpretation"],"additionalProperties":false},"contradictions":{"type":"array","items":{"type":"object","properties":{"fact_ids":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["fact_ids","description"],"additionalProperties":false}},"verified_at":{"type":"string","format":"date-time"},"limitations":{"type":"array","items":{"type":"string"}},"research":{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"tier":{"type":"string","enum":["quick","standard","deep"]},"queries":{"type":"array","items":{"type":"string"}},"demo":{"type":"boolean"}},"required":["provider","model","tier","queries","demo"],"additionalProperties":false}},"required":["schema_version","request_id","subject","claim","status","summary","confidence","confidence_kind","sources","facts","conclusion","contradictions","verified_at","limitations","research"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"Access":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"access_token":{"type":"string","description":"Returned only on POST. Keep secret."},"status_url":{"type":"string"},"result_url":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}