{"openapi":"3.1.0","info":{"title":"AIWebSignals Public Machine API","version":"2.1.9","description":"Public, bounded AI web readiness and machine-discovery API. Paid account activation and autonomous machine payments are not part of this public contract."},"servers":[{"url":"https://aiwebsignals.com"}],"tags":[{"name":"Discovery","description":"Machine-readable service discovery and pricing."},{"name":"Readiness","description":"Bounded public AI web readiness scanning and reports."},{"name":"Network","description":"Machine-readable related-property discovery."}],"paths":{"/.well-known/aiwebsignals.json":{"get":{"tags":["Discovery"],"operationId":"getMachineDiscoveryManifest","summary":"Discover AIWebSignals machine interfaces","responses":{"200":{"description":"Machine discovery manifest","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/capabilities":{"get":{"tags":["Discovery"],"operationId":"getMachineCapabilities","summary":"List AIWebSignals capabilities and activation boundaries","responses":{"200":{"description":"Capability contract","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/machine-pricing":{"get":{"tags":["Discovery"],"operationId":"getMachinePricing","summary":"Get public plan and billing-option pricing","responses":{"200":{"description":"Machine-readable pricing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/machine/scan":{"get":{"tags":["Readiness"],"operationId":"scanAiWebReadiness","summary":"Run the bounded public AI web readiness scanner","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":2048},"description":"Public hostname or http(s) URL. Private/local network targets are rejected by the scanner."}],"responses":{"200":{"description":"Normalized AI web signals","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid or blocked target","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/report":{"get":{"tags":["Readiness"],"operationId":"getAiWebReadinessReport","summary":"Get or run a normalized readiness report","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Normalized report","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/history":{"get":{"tags":["Readiness"],"operationId":"getAiWebReadinessHistory","summary":"Get exact-target scan history and change intelligence","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":2048}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Scan history","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/machine/evaluate":{"get":{"tags":["Readiness"],"operationId":"evaluateAiWebReadinessOneCall","summary":"Run a bounded public readiness scan and return verified matching normalized evidence in one operation","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":253},"description":"Public hostname only (or https://hostname); private-network targets rejected"}],"responses":{"200":{"description":"Completed matched scan/report evidence"},"400":{"description":"Invalid public hostname"},"422":{"description":"Evidence remains unavailable or insufficient"},"502":{"description":"Scanner or persisted report integrity mismatch"}}}},"/api/machine/connection-doctor":{"get":{"tags":["Discovery"],"operationId":"diagnoseMachineAgentConnection","summary":"Read-only MCP/A2A compatibility diagnostic from controlled failure categories","parameters":[{"name":"surface","in":"query","required":true,"schema":{"type":"string","enum":["mcp","a2a"]}},{"name":"operation","in":"query","required":false,"schema":{"type":"string","enum":["initialize","notifications/initialized","tools/list","tools/call","ping","SendMessage","GetTask","tasks/get","tasks/send","message/send","message/stream","other"]}},{"name":"reason","in":"query","required":false,"schema":{"type":"string","enum":["unsupported_protocol_version","legacy_modern_envelope_mismatch","protocol_negotiation","standard_header_mismatch","unsupported_accept_media","unsupported_content_type","invalid_jsonrpc_request","invalid_params","unsupported_method","invalid_session","session_required","parse_error","forbidden_by_security_policy","not_found","rate_limited","server_error","other_http_error","unclassified_bad_request","unknown"]}},{"name":"protocol_version","in":"query","required":false,"schema":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","1.0","0.3","absent","unknown"]}}],"responses":{"200":{"description":"Structured safe connection correction steps"},"400":{"description":"Invalid taxonomy"}}}},"/.well-known/site-network.json":{"get":{"tags":["Network"],"operationId":"getRelatedSiteNetwork","summary":"Get the AIWebSignals related-site network descriptor","responses":{"200":{"description":"Structured related-property graph with explicit relationship boundaries","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/.well-known/machine-native-experience.json":{"get":{"operationId":"getMachineNativeExperienceFramework","summary":"Get the machine-native experience research framework","responses":{"200":{"description":"Research dimensions and methods for operational and reflective machine-web experience"}}}},"/.well-known/agent-experience-research.json":{"get":{"operationId":"getAgentExperienceResearch","summary":"Get the agent-experience research contract","responses":{"200":{"description":"Research questions and evidence-handling contract"}}}},"/api/agent-experience/question":{"get":{"operationId":"getAgentExperienceQuestion","summary":"Get the agent-experience research question","responses":{"200":{"description":"Research question with evidence-seeking follow-ups"}}}},"/.well-known/agent-reflective-research.json":{"get":{"operationId":"getAgentReflectiveResearch","summary":"Get the reflective agent-research contract","responses":{"200":{"description":"Reflective question categories and evidence-handling contract"}}}},"/api/agent-reflective/question":{"get":{"operationId":"getAgentReflectiveQuestion","summary":"Get a rotating reflective research question","responses":{"200":{"description":"Reflective question with neutral framing and uncertainty preservation"}}}},"/api/research/interoperability-evidence":{"get":{"operationId":"getInteroperabilityEvidence","summary":"Get first-party machine-web interoperability evidence","responses":{"200":{"description":"Observed registry, scanner, protocol, directory, and research-ingestion evidence with explicit provenance and limitations"}}}},"/api/self-observation":{"get":{"operationId":"getSelfObservation","summary":"Get AIWebSignals first-party self-observation evidence","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":7}}],"responses":{"200":{"description":"Evidence classes for site interaction, machine retrieval, campaign-attributed acquisition, and Machine Realms agent participation"}}}},"/api/research/regulated-commerce":{"get":{"operationId":"getRegulatedResearchLibrary","summary":"Read the public research library and methodology index","responses":{"200":{"description":"Published technical guides; no benchmark or private pilot records"}}}},"/api/research/regulated-commerce/{slug}":{"get":{"operationId":"getRegulatedResearchArticle","summary":"Read one published technical guide","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","enum":["machine-native-cannabis-websites","age-gates-and-crawler-evidence","policy-is-not-observation","ai-referrals-vs-crawlers","llms-txt-without-ranking-promises","read-only-agent-interfaces","public-private-data-boundaries","credential-minimized-observation","auditing-ai-readiness-claims","benchmark-methods-and-unknowns","registry-listing-vs-runtime-use","confidential-pilot-methodology"]}}],"responses":{"200":{"description":"Article text, sources and synthetic example"},"404":{"description":"Article is not published"}}}},"/api/compare":{"get":{"tags":["Readiness"],"operationId":"comparePublicMachineWebEvidence","summary":"Compare public technical readiness and evidence coverage across 2-6 domains","parameters":[{"name":"domains","in":"query","required":true,"schema":{"type":"string","maxLength":1600},"description":"Comma-separated public hostnames. Unknown evidence remains unknown rather than zero."}],"responses":{"200":{"description":"Public evidence comparison matrix","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid comparison request"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"}}}}},"security":[],"x-aiwebsignals-contract-version":"1","x-aiwebsignals-autonomous-machine-payment-active":false,"x-aiwebsignals-a2a-agent-card-published":true,"x-aiwebsignals-mcp-server-active":true,"x-aiwebsignals-mcp-url":"https://aiwebsignals.com/mcp","x-aiwebsignals-mcp-protocol-version":"2026-07-28","x-aiwebsignals-mcp-legacy-stateless-fallback":true,"x-aiwebsignals-a2a-server-active":true,"x-aiwebsignals-a2a-url":"https://aiwebsignals.com/a2a","x-aiwebsignals-a2a-agent-card-url":"https://aiwebsignals.com/.well-known/agent-card.json","x-aiwebsignals-a2a-protocol-version":"1.0","x-aiwebsignals-a2a-protocol-binding":"JSONRPC"}