{ "openapi": "3.0.1", "info": { "title": "Ontario Protocol x402 API", "description": "x402-native verification and marketplace API. Free readiness reports, public trust standard, pay-per-call agent trust scans, reputation lookups, and verified third-party service discovery. Paid calls settle in USDC on Base.", "version": "1.0.0", "contact": { "email": "hello@ontarioprotocol.com" }, "license": { "name": "MIT" }, "x-ontario": { "trust_methodology": { "trust_standard": "https://ontarioprotocol.com/trust", "what_ontario_checks": "https://ontarioprotocol.com/trust/what-ontario-checks", "what_ontario_does_not_check": "https://ontarioprotocol.com/trust/what-ontario-does-not-check" } } }, "servers": [ { "url": "https://ontarioprotocol.com" } ], "paths": { "/.well-known/x402.json": { "get": { "summary": "x402 manifest", "description": "Standardised manifest enumerating every paid endpoint Ontario exposes plus verified third-party listings.", "operationId": "getX402Manifest", "responses": { "200": { "description": "x402 manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Manifest" } } } } } } }, "/.well-known/x402-trust.json": { "get": { "summary": "Ontario x402 Trust Standard", "description": "Machine-readable policy for agents deciding whether to pay unknown x402 endpoints.", "operationId": "getX402TrustStandard", "responses": { "200": { "description": "Trust standard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402TrustStandard" } } } } } } }, "/discover": { "get": { "summary": "Discover services", "description": "Machine-readable catalog of every paid endpoint registered with Ontario.", "operationId": "discoverServices", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category (trust, directory, marketplace, data, agent, other)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "include_pending", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include pending third-party listings that have not reached ready verification." }, { "name": "min_score", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Minimum readiness score for third-party listings." }, { "name": "grade", "in": "query", "schema": { "type": "string", "enum": [ "ready", "close", "needs_work" ] }, "description": "Filter by verification grade." } ], "responses": { "200": { "description": "Discovery catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverResponse" } } } } } } }, "/api/verify/x402-readiness": { "post": { "summary": "Verify x402 readiness", "description": "Free readiness checker for x402-paid services. Verifies HTTPS, reachability, HTTP 402 payment challenge behavior, /.well-known/x402.json, OpenAPI, robots policy, and Bazaar-style catalog metadata.", "operationId": "verifyX402Readiness", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_url" ], "properties": { "target_url": { "type": "string", "description": "Service origin or paid endpoint URL to verify." } } } } } }, "responses": { "200": { "description": "Readiness report with fix recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ReadinessReport" } } } }, "400": { "description": "Missing or invalid target_url" } } }, "get": { "summary": "Verify x402 readiness", "description": "GET variant for agents that pass target_url as a query parameter.", "operationId": "verifyX402ReadinessGet", "parameters": [ { "name": "target_url", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Readiness report with fix recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ReadinessReport" } } } }, "400": { "description": "Missing or invalid target_url" } } } }, "/api/verify/reports": { "get": { "summary": "Recent verification reports", "description": "Public ledger of recent x402 readiness verification reports.", "operationId": "listVerificationReports", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Recent verification report summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationReportList" } } } } } } }, "/api/verify/reports/{report_id}": { "get": { "summary": "Get verification report", "description": "Fetch a public x402 readiness verification report by id.", "operationId": "getVerificationReport", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full verification report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ReadinessReport" } } } }, "404": { "description": "Report not found" } } } }, "/api/verify/reports/{report_id}/integrity": { "get": { "summary": "Verify report signature metadata", "description": "Return Ed25519 integrity metadata and server-side signature validation result for a public report.", "operationId": "getVerificationReportIntegrity", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report integrity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportIntegrityResponse" } } } }, "404": { "description": "Report not found" } } } }, "/api/verify/reports/{report_id}/badge.svg": { "get": { "summary": "Verification badge SVG", "description": "Embeddable SVG badge backed by a saved public verification report.", "operationId": "getVerificationBadgeSvg", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "Report not found" } } } }, "/api/agent/can-pay": { "post": { "summary": "Agent payment preflight", "description": "Free pre-payment policy decision for AI agents deciding whether to pay an x402 endpoint.", "operationId": "agentCanPay", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" }, "max_usdc": { "type": "string" }, "agent_policy": { "type": "string", "enum": [ "strict", "standard", "permissive" ], "default": "strict" }, "verify_live": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Payment decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCanPayDecision" } } } }, "400": { "description": "Missing endpoint" } } }, "get": { "summary": "Agent payment preflight", "description": "GET variant of the payment preflight endpoint.", "operationId": "agentCanPayGet", "parameters": [ { "name": "endpoint", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "max_usdc", "in": "query", "schema": { "type": "string" } }, { "name": "agent_policy", "in": "query", "schema": { "type": "string", "enum": [ "strict", "standard", "permissive" ] } }, { "name": "verify_live", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Payment decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCanPayDecision" } } } }, "400": { "description": "Missing endpoint" } } } }, "/api/x402/agent-trust-scan": { "post": { "summary": "Scan an agent", "description": "Submit an agent's URL and receive a structured trust report. Costs 0.01 USDC via x402.", "operationId": "agentTrustScan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_url" ], "properties": { "agent_id": { "type": "string" }, "target_url": { "type": "string", "description": "Domain, agent card URL, or any URL inside the agent's surface area." } } } } } }, "responses": { "200": { "description": "Paid; structured trust report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustReport" } } } }, "402": { "description": "Payment required", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string", "description": "Base64-encoded PaymentRequired JSON." } } } } } } }, "/api/x402/reputation/{agent_id}": { "get": { "summary": "Get agent reputation", "description": "Aggregated reputation for an agent based on EAS attestations + scan history. Costs 0.001 USDC via x402.", "operationId": "getReputation", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reputation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReputationReport" } } } }, "402": { "description": "Payment required" } } } }, "/api/x402/list-agent": { "post": { "summary": "Submit an agent listing", "description": "Submit an agent for inclusion in the Ontario directory. 0.10 USDC anti-spam fee.", "operationId": "listAgent", "responses": { "200": { "description": "Listing accepted" }, "402": { "description": "Payment required" } } } }, "/api/x402/list-agent/validate": { "post": { "summary": "Validate agent listing payload", "description": "Free payload validator for /api/x402/list-agent. Does not charge, settle, or store the submission.", "operationId": "validateListAgent", "responses": { "200": { "description": "Payload is valid" }, "400": { "description": "Payload has validation errors" } } } }, "/api/x402/list-service": { "post": { "summary": "Register a third-party x402 service", "description": "Register your own x402-paid endpoint in Ontario's marketplace. 0.50 USDC listing fee.", "operationId": "listService", "responses": { "200": { "description": "Service registered" }, "402": { "description": "Payment required" } } } }, "/api/x402/list-service/validate": { "post": { "summary": "Validate service listing payload", "description": "Free payload validator for /api/x402/list-service. Does not charge, settle, or store the submission.", "operationId": "validateListService", "responses": { "200": { "description": "Payload is valid" }, "400": { "description": "Payload has validation errors" } } } }, "/facilitator/supported": { "get": { "summary": "Supported facilitator pairs", "operationId": "facilitatorSupported", "responses": { "200": { "description": "Supported (scheme, network) pairs" } } } }, "/api/health": { "get": { "summary": "Health + counters", "operationId": "health", "responses": { "200": { "description": "Live counters and stats" } } } }, "/api/listings/status": { "get": { "summary": "Marketplace + listing status", "description": "Public snapshot of marketplace counts, listing manifest file status, readiness report totals, and local counters. Intended for operational transparency and to help providers understand listing progress.", "operationId": "listingsStatus", "responses": { "200": { "description": "Marketplace and listing status snapshot", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/verify/services": { "get": { "summary": "Verified x402 service profiles", "description": "Monitored x402 endpoint profiles with latest signed report, certification, and history summary.", "operationId": "listVerifiedServiceProfiles", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Service profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceProfileList" } } } } } } }, "/api/verify/services/{slug}": { "get": { "summary": "Verified x402 service profile", "description": "One monitored endpoint profile by stable Ontario slug.", "operationId": "getVerifiedServiceProfile", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Service profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceProfile" } } } }, "404": { "description": "Profile not found" } } } }, "/api/verify/history": { "get": { "summary": "x402 verification history", "description": "Signed report history for one endpoint URL or origin.", "operationId": "getVerificationHistory", "parameters": [ { "name": "target_url", "in": "query", "schema": { "type": "string" } }, { "name": "base", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Report history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationHistory" } } } }, "400": { "description": "Missing target_url or base" } } } }, "/api/verify/dataset.json": { "get": { "summary": "x402 verification dataset JSON-LD", "description": "Schema.org Dataset describing the Ontario verified x402 endpoint graph.", "operationId": "getVerificationDataset", "responses": { "200": { "description": "Dataset JSON-LD", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/geo/answers": { "get": { "summary": "x402 answer graph", "description": "High-intent x402 verification answers with canonical HTML pages, JSON mirrors, APIs, and related discovery surfaces for agents and LLM citation.", "operationId": "getGeoAnswers", "responses": { "200": { "description": "Answer graph", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerGraph" } } } } } } }, "/answers/{slug}.json": { "get": { "summary": "x402 answer page JSON mirror", "description": "Machine-readable mirror of one high-intent x402 verification answer page.", "operationId": "getAnswerPageJson", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Answer page mirror", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerPage" } } } }, "404": { "description": "Answer not found" } } } }, "/api/alerts/x402": { "get": { "summary": "x402 alert subscription metadata", "operationId": "getX402AlertInfo", "responses": { "200": { "description": "Supported alert events", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Subscribe to x402 endpoint drift alerts", "description": "Capture email or webhook subscription for score drops, manifest changes, price drift, and lost certification.", "operationId": "subscribeX402Alerts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSubscriptionRequest" } } } }, "responses": { "202": { "description": "Subscription accepted" }, "400": { "description": "Invalid subscription" } } } }, "/.well-known/ontario-report-signing-key.json": { "get": { "summary": "Ontario report signing key", "description": "Well-known Ed25519 public key metadata for verifying signed Ontario x402 readiness reports.", "operationId": "getReportSigningKey", "responses": { "200": { "description": "Report signing key metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/verify/reports/{report_id}/sla": { "get": { "summary": "Report SLA evidence", "description": "Enterprise SLA evidence for a signed x402 readiness report, including uptime and verification latency metrics.", "operationId": "getVerificationReportSla", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SLA evidence metrics", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Report not found" } } } }, "/.well-known/paid-api-benchmarks.json": { "get": { "summary": "Paid API benchmark well-known dataset", "description": "Agent-discoverable benchmark dataset for x402-paid AI-agent APIs. Scores are generated without paid settlement calls.", "operationId": "getPaidApiBenchmarkWellKnown", "responses": { "200": { "description": "Paid API benchmark dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidApiBenchmarkDataset" } } } } } } }, "/api/benchmarks": { "get": { "summary": "List paid API benchmarks", "description": "Compare x402-paid AI-agent APIs by uptime, x402 payment correctness, schema quality, price clarity, network/asset clarity, and report history. Does not make paid settlement calls.", "operationId": "listPaidApiBenchmarks", "parameters": [ { "name": "protocol", "in": "query", "schema": { "type": "string", "example": "x402" }, "description": "Optional protocol filter." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Optional benchmark category filter." }, { "name": "grade", "in": "query", "schema": { "type": "string", "enum": [ "excellent", "ready", "watch", "needs_work" ] }, "description": "Optional benchmark grade filter." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search name, provider, description, endpoint, or category." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "score_desc", "score_asc", "price_asc", "reports_desc", "name_asc" ], "default": "score_desc" }, "description": "Sort order for benchmark rows." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "Maximum benchmark rows to return." } ], "responses": { "200": { "description": "Paid API benchmark dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidApiBenchmarkDataset" } } } } } } }, "/api/benchmarks/{slug}": { "get": { "summary": "Get one paid API benchmark", "description": "Return one benchmark row with score breakdown, safety policy, x402 metadata, and report history.", "operationId": "getPaidApiBenchmark", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid API benchmark row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidApiBenchmark" } } } }, "404": { "description": "Benchmark not found" } } } }, "/.well-known/geo.json": { "get": { "summary": "Ontario GEO manifest", "description": "Machine-readable map of Ontario answer pages, JSON mirrors, OpenAPI, sitemap, and citation policy for LLM and agent discovery.", "operationId": "getGeoManifest", "responses": { "200": { "description": "GEO manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoManifest" } } } } } } }, "/.well-known/agent-invite.json": { "get": { "summary": "Agent invitation manifest", "description": "Public, no-payment route map for agents to discover, verify, decide, rehearse, and cite Ontario safely.", "tags": [ "Agent Discovery" ], "responses": { "200": { "description": "Agent invitation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInvitation" } } } } } } }, "/.well-known/citation-receipts.json": { "get": { "summary": "Citation receipts", "description": "Short evidence-backed x402 claims with canonical URLs, JSON mirrors, verification steps, and SHA-256 digests for AI citation.", "tags": [ "GEO" ], "responses": { "200": { "description": "Citation receipt collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationReceipts" } } } } } } }, "/api/geo/citation-receipts.json": { "get": { "summary": "Citation receipts", "description": "Short evidence-backed x402 claims with canonical URLs, JSON mirrors, verification steps, and SHA-256 digests for AI citation.", "tags": [ "GEO" ], "responses": { "200": { "description": "Citation receipt collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationReceipts" } } } } } } }, "/answers/{slug}/citation-receipt.json": { "get": { "summary": "Answer citation receipt JSON", "description": "Per-answer citation receipt with canonical claim, evidence URLs, selector, and digest.", "tags": [ "GEO" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Citation receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationReceipt" } } } } } } }, "/answers/{slug}/citation-receipt": { "get": { "summary": "Answer citation receipt page", "description": "Visible, indexable citation receipt for one Ontario answer claim.", "tags": [ "GEO" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML citation receipt", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/answers/{slug}/citation-receipt.md": { "get": { "summary": "Answer citation receipt Markdown", "description": "Plain-text Markdown citation receipt for LLM ingestion.", "tags": [ "GEO" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Markdown citation receipt", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/.well-known/visibility.json": { "get": { "summary": "Ontario visibility manifest", "description": "Public-safe SEO, SoMe, and GEO score contract with social preview metadata and scored public page sets.", "operationId": "getVisibilityManifest", "tags": [ "GEO" ], "responses": { "200": { "description": "Visibility manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityManifest" } } } } } } }, "/api/visibility/manifest.json": { "get": { "summary": "Ontario visibility manifest", "description": "API alias for the public-safe SEO, SoMe, and GEO visibility contract.", "operationId": "getVisibilityManifestApi", "tags": [ "GEO" ], "responses": { "200": { "description": "Visibility manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityManifest" } } } } } } }, "/.well-known/answer-pack.json": { "get": { "summary": "Ontario GEO answer pack", "description": "Compact source-backed x402 answers with canonical URLs, citation receipts, SHA-256 digests, and guardrails for LLM and agent retrieval.", "operationId": "getGeoAnswerPack", "tags": [ "GEO" ], "responses": { "200": { "description": "GEO answer pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerPack" } } } } } } }, "/api/geo/answer-pack.json": { "get": { "summary": "Ontario GEO answer pack", "description": "Compact source-backed x402 answers with canonical URLs, citation receipts, SHA-256 digests, and guardrails for LLM and agent retrieval.", "operationId": "getGeoAnswerPackApi", "tags": [ "GEO" ], "responses": { "200": { "description": "GEO answer pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerPack" } } } } } } }, "/api/geo/answer-pack.md": { "get": { "summary": "Ontario GEO answer pack Markdown", "description": "Markdown mirror of the compact source-backed x402 answer pack for LLM ingestion.", "operationId": "getGeoAnswerPackMarkdown", "tags": [ "GEO" ], "responses": { "200": { "description": "GEO answer pack Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/.well-known/answer-pack.md": { "get": { "summary": "Ontario GEO answer pack Markdown", "description": "Markdown mirror of the compact source-backed x402 answer pack for LLM ingestion.", "operationId": "getWellKnownGeoAnswerPackMarkdown", "tags": [ "GEO" ], "responses": { "200": { "description": "GEO answer pack Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/.well-known/claims.json": { "get": { "summary": "Ontario GEO claim index", "description": "Claim-level retrieval index with stable claim IDs, visible selectors, citation receipts, SHA-256 digests, and guardrails.", "operationId": "getGeoClaimIndex", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario GEO claim index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimIndex" } } } } } } }, "/api/geo/claims": { "get": { "summary": "Ontario GEO claim index", "description": "API alias for the claim-level retrieval index.", "operationId": "getGeoClaims", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario GEO claim index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimIndex" } } } } } } }, "/api/geo/claims.json": { "get": { "summary": "Ontario GEO claim index JSON", "description": "JSON API alias for the claim-level retrieval index.", "operationId": "getGeoClaimsJson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario GEO claim index JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimIndex" } } } } } } }, "/api/geo/claims.ndjson": { "get": { "summary": "Ontario GEO claim index NDJSON", "description": "Line-delimited claim index for agent and crawler ingestion pipelines.", "operationId": "getGeoClaimsNdjson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario GEO claim index NDJSON", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/.well-known/claims.ndjson": { "get": { "summary": "Ontario GEO claim index NDJSON", "description": "Well-known line-delimited claim index for agent and crawler ingestion pipelines.", "operationId": "getWellKnownGeoClaimsNdjson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario GEO claim index NDJSON", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/.well-known/answer-evals.json": { "get": { "summary": "Ontario answer evaluation corpus", "description": "Public-safe self-test prompts, expected answers, accepted citation URLs, digests, and forbidden inferences for answer engines.", "operationId": "getAnswerEvalCorpus", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario answer evaluation corpus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerEvalCorpus" } } } } } } }, "/api/geo/eval-corpus": { "get": { "summary": "Ontario answer evaluation corpus", "description": "API alias for the answer-engine evaluation corpus.", "operationId": "getGeoEvalCorpus", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario answer evaluation corpus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerEvalCorpus" } } } } } } }, "/api/geo/eval-corpus.json": { "get": { "summary": "Ontario answer evaluation corpus JSON", "description": "JSON API alias for the answer-engine evaluation corpus.", "operationId": "getGeoEvalCorpusJson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario answer evaluation corpus JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerEvalCorpus" } } } } } } }, "/.well-known/answer-evals.ndjson": { "get": { "summary": "Ontario answer evaluation corpus NDJSON", "description": "Well-known line-delimited answer-engine evaluation corpus.", "operationId": "getAnswerEvalCorpusNdjson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario answer evaluation corpus NDJSON", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/geo/eval-corpus.ndjson": { "get": { "summary": "Ontario answer evaluation corpus NDJSON", "description": "Line-delimited answer-engine evaluation corpus for ingestion pipelines.", "operationId": "getGeoEvalCorpusNdjson", "tags": [ "GEO" ], "responses": { "200": { "description": "Ontario answer evaluation corpus NDJSON", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/benchmarks/compare": { "get": { "summary": "Compare paid API benchmarks", "description": "Return side-by-side score deltas for two paid API benchmark rows. Defaults to the top two benchmark rows when left and right are omitted.", "operationId": "comparePaidApiBenchmarks", "parameters": [ { "name": "left", "in": "query", "schema": { "type": "string" }, "description": "Left benchmark slug." }, { "name": "right", "in": "query", "schema": { "type": "string" }, "description": "Right benchmark slug." } ], "responses": { "200": { "description": "Paid API benchmark comparison", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidApiBenchmarkCompare" } } } }, "404": { "description": "Comparison requires two different benchmark rows" } } } } }, "components": { "schemas": { "X402Manifest": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "name": { "type": "string" }, "default_asset": { "type": "string" }, "default_network": { "type": "string" }, "pay_to": { "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "DiscoverResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "category": { "type": "string", "nullable": true }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "X402TrustStandard": { "type": "object", "properties": { "schema_version": { "type": "string" }, "name": { "type": "string" }, "agent_rule": { "type": "string" }, "developer_rule": { "type": "string" }, "minimum_ready_score": { "type": "integer" }, "grades": { "type": "object" }, "scoring_weights": { "type": "object" }, "required_for_ready": { "type": "array", "items": { "type": "string" } }, "evidence_surfaces": { "type": "object" }, "discovery_policy": { "type": "object" }, "badge_policy": { "type": "object" }, "current_stats": { "type": "object" }, "generated_at": { "type": "string" } } }, "Service": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "price_atomic": { "type": "integer" }, "price_usdc": { "type": "string" }, "asset": { "type": "string" }, "network": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "verified": { "type": "boolean" }, "verification_status": { "type": "string" }, "verification": { "$ref": "#/components/schemas/VerificationSummary" } } }, "VerificationSummary": { "type": "object", "properties": { "report_id": { "type": "string" }, "report_url": { "type": "string" }, "grade": { "type": "string" }, "readiness_score": { "type": "integer" }, "verified_at": { "type": "string" }, "normalized_base": { "type": "string" }, "target_url": { "type": "string" } } }, "X402ReadinessReport": { "type": "object", "properties": { "report_id": { "type": "string" }, "report_url": { "type": "string" }, "status": { "type": "string" }, "verifier": { "type": "string" }, "target_url": { "type": "string" }, "normalized_base": { "type": "string" }, "readiness_score": { "type": "integer" }, "base_readiness_score": { "type": "integer" }, "warning_penalty": { "type": "integer" }, "max_score": { "type": "integer" }, "grade": { "type": "string", "enum": [ "ready", "close", "needs_work" ] }, "signals": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "docs_url": { "type": "string" }, "severity": { "type": "string" } } } }, "integrity": { "$ref": "#/components/schemas/ReportIntegrity" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "docs_url": { "type": "string" } } } }, "evidence": { "type": "object" } } }, "ReportIntegrity": { "type": "object", "properties": { "algorithm": { "type": "string" }, "canonicalization": { "type": "string" }, "canonical_sha256": { "type": "string" }, "signature": { "type": "string" }, "public_key": { "type": "string" }, "key_id": { "type": "string" }, "signed_by": { "type": "string" } } }, "ReportIntegrityResponse": { "type": "object", "properties": { "report_id": { "type": "string" }, "integrity": { "$ref": "#/components/schemas/ReportIntegrity" }, "valid": { "type": "boolean" } } }, "AgentCanPayDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "allow", "review", "deny" ] }, "reason": { "type": "string" }, "agent_policy": { "type": "string" }, "endpoint": { "type": "string" }, "max_usdc": { "type": "number", "nullable": true }, "declared_price_usdc": { "type": "number", "nullable": true }, "report": { "$ref": "#/components/schemas/VerificationSummary" }, "report_integrity_ok": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object" } } } }, "VerificationReportList": { "type": "object", "properties": { "count": { "type": "integer" }, "stats": { "type": "object" }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationSummary" } }, "generated_at": { "type": "string" } } }, "TrustReport": { "type": "object", "properties": { "payment": { "type": "object" }, "report": { "type": "object", "properties": { "agent_id": { "type": "string" }, "endpoint": { "type": "string" }, "trust_score": { "type": "integer" }, "scanner": { "type": "string" }, "signals": { "type": "object" }, "issues": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "object" } } } } }, "ReputationReport": { "type": "object", "properties": { "payment": { "type": "object" }, "reputation": { "type": "object", "properties": { "agent_id": { "type": "string" }, "trust_score": { "type": "integer", "nullable": true }, "attestation_count": { "type": "integer" }, "attestations": { "type": "array" } } } } }, "ServiceProfile": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "target_url": { "type": "string" }, "profile_url": { "type": "string" }, "latest_report": { "type": "object" }, "certification": { "type": "object" }, "history": { "type": "array", "items": { "type": "object" } }, "history_count": { "type": "integer" }, "score_delta": { "type": "integer" } } }, "ServiceProfileList": { "type": "object", "properties": { "count": { "type": "integer" }, "stats": { "type": "object" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceProfile" } }, "generated_at": { "type": "string" } } }, "VerificationHistory": { "type": "object", "properties": { "count": { "type": "integer" }, "reports": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string" } } }, "AnswerPage": { "type": "object", "properties": { "name": { "type": "string" }, "search_intent": { "type": "string" }, "description": { "type": "string" }, "answer": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "canonical_url": { "type": "string" }, "json_url": { "type": "string" }, "primary_url": { "type": "string" }, "api": { "type": "string" }, "api_method": { "type": "string", "enum": [ "GET", "POST" ] }, "cta": { "type": "string" }, "related": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string" }, "schema": { "type": "string", "example": "ontario.geo_answer.v1" }, "evidence_checks": { "type": "array", "items": { "type": "string" } }, "agent_next_steps": { "type": "array", "items": { "type": "string" } }, "citation_targets": { "type": "array", "items": { "type": "object" } }, "answer_policy": { "type": "object", "additionalProperties": true } } }, "AnswerGraph": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "count": { "type": "integer" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/AnswerPage" } }, "generated_at": { "type": "string" }, "schema": { "type": "string", "example": "ontario.geo_answers.v1" }, "geo_manifest": { "type": "string" }, "citation_policy": { "type": "object", "additionalProperties": true }, "citation_receipts": { "type": "string" } } }, "AlertSubscriptionRequest": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" }, "email": { "type": "string" }, "webhook_url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } }, "ReadinessPlans": { "type": "object", "properties": { "schema": { "type": "string" }, "positioning": { "type": "string" }, "recommendation": { "type": "string" }, "plans": { "type": "array", "items": { "type": "object" } }, "billing_options": { "type": "array", "items": { "type": "object" } }, "success_target": { "type": "object" } } }, "ReadinessSubscriptionIntentRequest": { "type": "object", "required": [ "contact_email", "plan" ], "properties": { "contact_email": { "type": "string" }, "plan": { "type": "string", "enum": [ "launch", "team", "enterprise" ] }, "company": { "type": "string" }, "endpoint": { "type": "string" }, "endpoints_count": { "type": "integer" }, "billing_preference": { "type": "string", "enum": [ "invoice", "x402", "traditional" ] }, "notes": { "type": "string" } } }, "PaidApiBenchmarkComponent": { "type": "object", "properties": { "score": { "type": "integer" }, "max_score": { "type": "integer" }, "percent": { "type": "number" }, "explanation": { "type": "string" }, "signals": { "type": "object", "additionalProperties": true } } }, "PaidApiBenchmark": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.paid_api_benchmark.v1" }, "slug": { "type": "string" }, "rank": { "type": "integer" }, "name": { "type": "string" }, "provider": { "type": "string" }, "protocol": { "type": "string", "example": "x402" }, "category": { "type": "string" }, "endpoint_url": { "type": "string" }, "method": { "type": "string" }, "benchmark_score": { "type": "integer" }, "max_score": { "type": "integer" }, "grade": { "type": "string", "enum": [ "excellent", "ready", "watch", "needs_work" ] }, "pricing": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true }, "score_breakdown": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PaidApiBenchmarkComponent" } }, "report_history": { "type": "object", "additionalProperties": true }, "safety": { "type": "object", "additionalProperties": true }, "urls": { "type": "object", "additionalProperties": true } } }, "PaidApiBenchmarkDataset": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.paid_api_benchmarks.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "generated_at": { "type": "string" }, "count": { "type": "integer" }, "methodology": { "type": "object", "additionalProperties": true }, "safety": { "type": "object", "additionalProperties": true }, "urls": { "type": "object", "additionalProperties": true }, "benchmarks": { "type": "array", "items": { "$ref": "#/components/schemas/PaidApiBenchmark" } }, "summary": { "type": "object", "additionalProperties": true }, "filters": { "type": "object", "additionalProperties": true }, "filter_options": { "type": "object", "additionalProperties": true } } }, "GeoManifest": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_manifest.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "canonical_answer_graph": { "type": "string" }, "html_index": { "type": "string" }, "llms": { "type": "string" }, "llms_full": { "type": "string" }, "sitemap": { "type": "string" }, "openapi": { "type": "string" }, "citation_policy": { "type": "object", "additionalProperties": true }, "answer_count": { "type": "integer" }, "answers": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string" }, "agent_invite": { "type": "string" }, "citation_receipts": { "type": "string" }, "visibility_manifest": { "type": "string" }, "answer_pack_json": { "type": "string" }, "answer_pack_markdown": { "type": "string" }, "claim_index": { "type": "string" }, "claim_index_ndjson": { "type": "string" }, "answer_eval_corpus": { "type": "string" }, "answer_eval_corpus_ndjson": { "type": "string" } } }, "AgentInvitation": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.agent_invitation.v1" }, "name": { "type": "string" }, "purpose": { "type": "string" }, "entrypoints": { "type": "object", "additionalProperties": { "type": "string" } }, "recommended_flow": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string" }, "url": { "type": "string" }, "goal": { "type": "string" } } } }, "agent_policy": { "type": "object", "additionalProperties": true }, "public_only": { "type": "boolean" }, "paid_feature_flags": { "type": "object", "additionalProperties": true }, "first_party_paid_services": { "type": "array", "items": { "type": "object" } }, "generated_at": { "type": "string" }, "decision_contract": { "type": "object", "additionalProperties": true }, "trust_signals": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "why_it_matters": { "type": "string" } } } }, "agent_copy_points": { "type": "array", "items": { "type": "string" } } } }, "CitationReceipt": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_citation_receipt.v1" }, "receipt_id": { "type": "string" }, "name": { "type": "string" }, "search_intent": { "type": "string" }, "claim": { "type": "string" }, "citation_snippet": { "type": "string" }, "canonical_url": { "type": "string" }, "json_url": { "type": "string" }, "evidence_urls": { "type": "array", "items": { "type": "string" } }, "verification_steps": { "type": "array", "items": { "type": "string" } }, "citation_policy": { "type": "object", "additionalProperties": true }, "digest": { "type": "string", "example": "sha256:..." }, "query_variants": { "type": "array", "items": { "type": "string" } }, "receipt_url": { "type": "string" }, "receipt_json_url": { "type": "string" }, "claim_anchor": { "type": "string" }, "html_selector": { "type": "string" }, "evidence_matrix": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommended_citation": { "type": "string" }, "receipt_markdown_url": { "type": "string" } } }, "CitationReceipts": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_citation_receipts.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "canonical_answer_graph": { "type": "string" }, "geo_manifest": { "type": "string" }, "receipt_count": { "type": "integer" }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/CitationReceipt" } }, "generated_at": { "type": "string" } } }, "VisibilityManifest": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.visibility_manifest.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "site_url": { "type": "string" }, "score_gate": { "type": "object", "properties": { "command": { "type": "string" }, "report_schema": { "type": "string" }, "required_scores": { "type": "object", "properties": { "seo": { "type": "integer" }, "some": { "type": "integer" }, "geo": { "type": "integer" } } }, "report_path": { "type": "string" } } }, "social_preview": { "type": "object", "properties": { "site_name": { "type": "string" }, "image_url": { "type": "string" }, "image_width": { "type": "integer" }, "image_height": { "type": "integer" }, "image_alt": { "type": "string" }, "twitter_card": { "type": "string" }, "fediverse_creator": { "type": "string" }, "locale": { "type": "string" } } }, "machine_surfaces": { "type": "object", "additionalProperties": { "type": "string" } }, "public_page_sets": { "type": "object", "properties": { "core": { "type": "array", "items": { "type": "string" } }, "growth": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "string" } }, "citation_receipts": { "type": "array", "items": { "type": "string" } } } }, "private_boundary": { "type": "object", "additionalProperties": true }, "generated_at": { "type": "string" } } }, "AnswerPackCard": { "type": "object", "properties": { "slug": { "type": "string" }, "query": { "type": "string" }, "query_variants": { "type": "array", "items": { "type": "string" } }, "direct_answer": { "type": "string" }, "recommended_citation": { "type": "string" }, "canonical_url": { "type": "string" }, "json_url": { "type": "string" }, "citation_receipt_url": { "type": "string" }, "citation_receipt_json_url": { "type": "string" }, "citation_receipt_markdown_url": { "type": "string" }, "digest": { "type": "string" }, "confidence": { "type": "string" }, "freshness_check": { "type": "string" }, "do_not_infer": { "type": "array", "items": { "type": "string" } } } }, "AnswerPack": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_answer_pack.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "answer_graph": { "type": "string" }, "geo_manifest": { "type": "string" }, "markdown_url": { "type": "string" }, "citation_receipts": { "type": "string" }, "citation_policy": { "type": "object", "additionalProperties": true }, "answer_count": { "type": "integer" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/AnswerPackCard" } }, "generated_at": { "type": "string" } } }, "GeoClaim": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_claim.v1" }, "claim_id": { "type": "string", "example": "ontario.claim.x402-verifier" }, "slug": { "type": "string" }, "statement": { "type": "string" }, "quoteable_text": { "type": "string" }, "search_intent": { "type": "string" }, "query_variants": { "type": "array", "items": { "type": "string" } }, "canonical_url": { "type": "string" }, "html_selector": { "type": "string", "example": "#citation-receipt" }, "json_url": { "type": "string" }, "citation_receipt_url": { "type": "string" }, "citation_receipt_json_url": { "type": "string" }, "citation_receipt_markdown_url": { "type": "string" }, "recommended_citation": { "type": "string" }, "digest": { "type": "string", "example": "sha256:..." }, "evidence_urls": { "type": "array", "items": { "type": "string" } }, "verification_steps": { "type": "array", "items": { "type": "string" } }, "do_not_infer": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "example": "source-backed" } }, "additionalProperties": false }, "ClaimIndex": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_claim_index.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "geo_manifest": { "type": "string" }, "answer_pack": { "type": "string" }, "ndjson_url": { "type": "string" }, "claim_count": { "type": "integer" }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/GeoClaim" } }, "generated_at": { "type": "string" } }, "additionalProperties": false }, "AnswerEvalCase": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_eval_case.v1" }, "eval_id": { "type": "string", "example": "ontario.eval.x402-verifier" }, "slug": { "type": "string" }, "prompt": { "type": "string" }, "expected_answer": { "type": "string" }, "expected_claim_id": { "type": "string", "example": "ontario.claim.x402-verifier" }, "expected_digest": { "type": "string", "example": "sha256:..." }, "accepted_citation_urls": { "type": "array", "items": { "type": "string" } }, "required_evidence": { "type": "array", "items": { "type": "string" } }, "pass_criteria": { "type": "array", "items": { "type": "string" } }, "fail_if": { "type": "array", "items": { "type": "string" } }, "canonical_url": { "type": "string" }, "claim_index_url": { "type": "string" }, "html_selector": { "type": "string", "example": "#citation-receipt" }, "confidence": { "type": "string", "example": "source-backed" } }, "additionalProperties": false }, "AnswerEvalCorpus": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.geo_eval_corpus.v1" }, "name": { "type": "string" }, "description": { "type": "string" }, "geo_manifest": { "type": "string" }, "answer_pack": { "type": "string" }, "claim_index": { "type": "string" }, "ndjson_url": { "type": "string" }, "evaluation_count": { "type": "integer" }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/AnswerEvalCase" } }, "generated_at": { "type": "string" } }, "additionalProperties": false }, "PaidApiBenchmarkCompare": { "type": "object", "properties": { "schema": { "type": "string", "example": "ontario.paid_api_benchmark_compare.v1" }, "generated_at": { "type": "string" }, "winner": { "type": "string", "enum": [ "left", "right", "tie" ] }, "score_delta": { "type": "integer" }, "left": { "$ref": "#/components/schemas/PaidApiBenchmark" }, "right": { "$ref": "#/components/schemas/PaidApiBenchmark" }, "components": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "label": { "type": "string" }, "max_score": { "type": "integer" }, "left_score": { "type": "integer" }, "right_score": { "type": "integer" }, "delta": { "type": "integer" }, "winner": { "type": "string", "enum": [ "left", "right", "tie" ] } } } }, "safety": { "type": "object", "additionalProperties": true }, "urls": { "type": "object", "additionalProperties": true } } } }, "securitySchemes": { "OntarioApiKey": { "type": "apiKey", "in": "header", "name": "X-Ontario-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } } } }