{ "openapi": "3.1.0", "info": { "title": "Known Good", "version": "1.7.0", "description": "Agentic search engine for AI agents: an index of websites verified usable by agents — every capability probed and tested live, tier 1–3 (declared · probe-verified · behaviourally verified), dated and citable. find_capability answers \"who can do X\"; get_site_report answers \"is this specific host agent-ready\", returning the dated evidence for one site. Nothing is hand-picked and placement cannot be bought: an automated probe decides. Human index of working MCP servers: https://knowngood.sh/mcp-servers", "contact": { "url": "https://knowngood.sh/api" }, "license": { "name": "Data returned is citable; see the rubric", "url": "https://knowngood.sh/benchmark" } }, "servers": [ { "url": "https://knowngood.sh" } ], "paths": { "/api/find": { "get": { "operationId": "find_capability", "summary": "Find agent-ready websites", "description": "Find websites where an agent can accomplish a task. Returns probe-verified agent-readiness signals, unverified apparent actions read from page content, the verification tier, how each site was found (it declared agent access, probe discovery, or it was submitted), and a report URL to cite. Returns count:0 with an empty_note when nothing in the index matches — never a nearest guess.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "What you are trying to do, in plain language. Optional when at least one filter is set: with no query the tool lists every listed site matching the filters, in a fixed published order, with `total`.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2, e.g. GB", "schema": { "type": "string" } }, { "name": "entity_type", "in": "query", "required": false, "description": "One of: business, ecommerce, saas, documentation, media, blog, government, education, nonprofit, personal, community, directory, tool, other", "schema": { "type": "string", "enum": [ "business", "ecommerce", "saas", "documentation", "media", "blog", "government", "education", "nonprofit", "personal", "community", "directory", "tool", "other" ] } }, { "name": "transactional", "in": "query", "required": false, "description": "Only sites where an agent can act, not just read", "schema": { "type": "boolean" } }, { "name": "has_mcp", "in": "query", "required": false, "description": "Only sites whose MCP server answered tools/list when we tested; results include the tool names", "schema": { "type": "boolean" } }, { "name": "has_md", "in": "query", "required": false, "description": "Only sites with verified markdown: negotiation that passed the strict re-grade (the body is markdown and differs from the HTML), or a .md twin. Omit both class flags for the whole index — the default.", "schema": { "type": "boolean" } }, { "name": "has_endpoint", "in": "query", "required": false, "description": "Only sites with a verified endpoint surface (working MCP server or API catalog).", "schema": { "type": "boolean" } }, { "name": "has_webmcp", "in": "query", "required": false, "description": "Only sites whose in-page WebMCP tools were RUNTIME-VERIFIED: the page was executed in a headless browser with a modelContext supplied, and it registered at least one tool. Source-only hosts — the registration code is present but registers nothing when the page runs — are excluded, exactly as an MCP card that never answers is. Results include the registered tool names.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 25 } } ], "responses": { "200": { "description": "Results, possibly zero. A zero is an honest zero.", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": [ "string", "null" ], "description": "The query, or null in filter-only mode." }, "mode": { "type": "string", "enum": [ "search", "filter" ], "description": "search: ranked by relevance to q. filter: no q, every listed site matching the filters, in a fixed order." }, "count": { "type": "integer", "description": "Rows in this response." }, "total": { "type": "integer", "description": "Filter-only mode: how many listed sites match the filters." }, "order": { "type": "string", "description": "Filter-only mode: the order, always \"platform subdomains last (as the flag policy publishes), then readiness score (checks passed, of 5) descending, then most recent probe first, then hostname\"." }, "empty_note": { "type": "string", "description": "Present when count is 0. Never a nearest guess. When a filter applied, it also says which, and how many listed sites have no known value for it and so could not be judged." }, "filter_completeness": { "type": "object", "description": "Per applied filter, how many listed hosts are excluded because the value is UNKNOWN rather than non-matching." }, "page_not_filled": { "type": "object", "description": "Present when a search returned fewer rows than limit and there is a reason other than 'nothing else matched'. With has_md or has_endpoint the search went deeper and still came up short: requested, returned, candidates_searched, and reason population_exhausted, depth_limit or could_not_search_deeper. Without them, reason below_relative_floor: candidates_cut rows scored below floor_fraction of the best match and were left out as weak." }, "results": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Missing or invalid parameter: neither q nor any narrowing filter, or a filter value outside its vocabulary", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable. May be reworded; do not match on it." }, "code": { "type": "string", "description": "Stable machine-readable code. This is the contract.", "enum": [ "MISSING_PARAM", "INVALID_FILTER_VALUE", "NOT_FOUND", "RATE_LIMITED" ] }, "hint": { "type": "string" }, "valid": { "type": "array", "items": { "type": "string" }, "description": "Present when the value had to come from a closed vocabulary." }, "see": { "type": "string", "format": "uri" } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable. May be reworded; do not match on it." }, "code": { "type": "string", "description": "Stable machine-readable code. This is the contract.", "enum": [ "MISSING_PARAM", "INVALID_FILTER_VALUE", "NOT_FOUND", "RATE_LIMITED" ] }, "hint": { "type": "string" }, "valid": { "type": "array", "items": { "type": "string" }, "description": "Present when the value had to come from a closed vocabulary." }, "see": { "type": "string", "format": "uri" } } } } } } } } }, "/api/stats": { "get": { "operationId": "stats", "summary": "Index-level figures, dated", "responses": { "200": { "description": "Figures with a generation stamp", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP over streamable HTTP", "description": "JSON-RPC. tools/list and tools/call for check_webmcp and find_capability and get_site_report.", "responses": { "200": { "description": "JSON-RPC result", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/a2a": { "post": { "operationId": "a2a", "summary": "A2A, JSONRPC binding", "description": "message/send only. Skills: check-webmcp, find-capability, get-site-report. streaming and pushNotifications are false in the agent card.", "responses": { "200": { "description": "A completed Task", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "x-report-tool": { "operationId": "get_site_report", "description": "Fetch Known Good's dated verification report for one listed website: which capabilities were tested, which passed, when it was probed, what an agent can apparently do there, and how the site was found: whether it declared agent access, came from probe discovery, or was submitted. Answers \"is this specific host agent-ready?\". Returns found:false for anything not in the index — it never guesses a nearest match. Cite the report URL and its date." } }