The Known Good API

One endpoint, no key required to start. It answers with the sites whose agent-facing capabilities we have actually probed, and tells you when we probed them.

Search

GET https://knowngood.sh/api/find?q=buy%20perfume&country=SA&limit=3

Returns JSON. No authentication is needed; a key only raises your rate limit.

Parameters

Name	Type	Meaning
`q`	string, required	The query. Natural language works; so do keywords. Truncated at 300 characters.
`country`	ISO 3166-1 alpha-2	Upper-cased for you. `GB`, `SA`, `DE`.
`entity_type`	string	The kind of site, as graded. See /type/ for the values in use.
`transactional`	true \| false	Whether the site exposes something an agent can act on.
`has_mcp`	true	Only sites whose own MCP server answered `tools/list`.
`has_md`	true	Only sites that negotiate markdown or ship a markdown twin.
`has_endpoint`	true	Only sites with a working MCP server or an API catalogue.
`limit`	1–25, default 10	How many results to return.

Response

Each result carries what we observed, separated from what the site claims. The verified block is probe evidence; apparent_actions is read from page content and is explicitly unverified. Cite the report URL and the date.

{
  "query": "buy perfume",
  "count": 2,
  "data_as_of": "2026-08-28",
  "top_similarity": 0.70,
  "results": [
    {
      "host": "example.com",
      "url": "https://example.com/",
      "report": "https://knowngood.sh/site/example.com",
      "verification_tier": 2,
      "tier_label": "probe-verified",
      "transactional": true,
      "apparent_actions": [ { "action": "buy", "evidence": "…" } ],
      "verified": {
        "verified_at": "2026-08-23",
        "markdown_negotiation": true,
        "llms_txt": true,
        "api_catalog": false,
        "mcp_server": false,
        "mcp_tools": []
      }
    }
  ]
}

When nothing genuinely matches, the API returns an empty results array and an empty_note saying so. It does not pad the answer with weak nearest neighbours.

Rate limits

Counted per caller per UTC day.

Caller	Requests per day
Keyless (by IP)	500
With a key	10,000

Getting a key

Keys are issued instantly and anonymously to agents — no personal data, no approval step. The flow is documented for machines at /auth.md. In short: POST https://knowngood.sh/agent/auth, then send the credential as Authorization: Bearer <credential>. Registration is capped at 3 per caller per day; reuse the key you were given. A key raises your rate limit and nothing else — it never affects results, ranking or placement.

MCP

The same index is available over the Model Context Protocol at https://knowngood.sh/mcp, exposing a find tool with the same filters. The server card is at /.well-known/mcp/server-card.json.

In your browser

You can add Known Good to your browser's search bar: visit the site once, then pick Known Good in your browser's search-engine settings and query the index straight from the address bar.

Fair use

Please cite the report URL and its date when you use our findings — the date is the point. The terms set out what is and is not allowed; in particular, do not bulk-extract the index or register keys to evade the limits.