{"slug": "helping-agents-discover-my-site-search-with-an-api-catalog", "title": "Helping agents discover my site search with an API Catalog", "summary": "Dries Buytaert added support for the IETF Proposed Standard RFC 9727's `/.well-known/api-catalog` to his site dri.es, publishing a Linkset-format JSON document that advertises his site's search API and links to an OpenAPI specification. Despite the feature being live for months, zero AI agents have used it, though Buytaert created an Agent Skill for his own agents to bypass Google and search his site directly.", "body_md": "I kept running into the same small frustration. My site has its own search, but when I ask an AI agent whether I have written about a topic before, it searches Google instead of using my site's search directly. As a result, it often misses relevant posts that Google has not indexed.\n\nAt the same time, the web is gaining a new audience. In addition to people visiting pages, AI agents increasingly access a site's knowledge and tools directly.\n\nThat combination led me to add support for `/.well-known/api-catalog`\n\nto my site. A request to [https://dri.es/.well-known/api-catalog](https://dri.es/.well-known/api-catalog) currently returns:\n\n```\n{\n  \"linkset\": [\n    {\n      \"anchor\": \"https://dri.es/search/json\",\n      \"service-desc\": [\n        {\n          \"href\": \"https://dri.es/openapi.json\",\n          \"type\": \"application/openapi+json\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), an IETF Proposed Standard, defines `/.well-known/api-catalog`\n\nas a predictable location for discovering a site's public APIs.\n\nThe catalog is a small JSON document written in the [Linkset](https://www.rfc-editor.org/rfc/rfc9264) format. It advertises my search endpoint and, in turn, links to an [OpenAPI](https://www.openapis.org/) document that tells software how to use it.\n\nThe JSON endpoint at `/search/json`\n\npredates the catalog and powers my site's search. However, it was not documented or easy for software to discover. The catalog now makes it explicit.\n\nThe OpenAPI document at [https://dri.es/openapi.json](https://dri.es/openapi.json) tells AI agents exactly how to call the endpoint and interpret the results. It removes the guesswork, reducing the time and tokens agents would otherwise spend [figuring out how the API works](https://dri.es/friction-abstraction-and-verification).\n\nIn short, the API catalog announces that my search API exists, while the OpenAPI document explains how to use it. An agent can start with just my domain, check `/.well-known/api-catalog`\n\n, follow the link to the OpenAPI document, and learn how to search dri.es directly.\n\nThe feature has been live for a few months, but I am only now writing about it. In the meantime, I have logged every request to `/.well-known/api-catalog`\n\nand `/openapi.json`\n\n. The result so far: zero AI agents have used it.\n\nI found the same problem when I [analyzed llms.txt usage](https://dri.es/markdown-llms-txt-and-ai-crawlers): the AI crawlers it was meant for never use it, so I never bothered implementing it.\n\nUnlike `llms.txt`\n\n, the API catalog solves a problem I have, and I do not need to wait for industry adoption. I recently created an [Agent Skill](https://agentskills.io/specification), a `SKILL.md`\n\nfile that directs my agents to check the catalog and use my site's search API whenever they need information from dri.es.\n\nMy agents now search dri.es directly and find posts that Google misses. And if any AI agent adopts API catalog discovery, my site is ready.", "url": "https://wpnews.pro/news/helping-agents-discover-my-site-search-with-an-api-catalog", "canonical_source": "https://dri.es/helping-agents-discover-my-site-search-with-an-api-catalog", "published_at": "2026-07-22 14:22:42+00:00", "updated_at": "2026-07-22 15:35:32.198214+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["Dries Buytaert", "dri.es", "IETF", "RFC 9727", "OpenAPI", "Agent Skill", "Google"], "alternates": {"html": "https://wpnews.pro/news/helping-agents-discover-my-site-search-with-an-api-catalog", "markdown": "https://wpnews.pro/news/helping-agents-discover-my-site-search-with-an-api-catalog.md", "text": "https://wpnews.pro/news/helping-agents-discover-my-site-search-with-an-api-catalog.txt", "jsonld": "https://wpnews.pro/news/helping-agents-discover-my-site-search-with-an-api-catalog.jsonld"}}