Why it matters
- RFC 9727 sets a fixed address, /.well-known/api-catalog, where a program or an agent finds the site's APIs, each with its description (OpenAPI) and documentation.
- A broken catalog is worse than none: the agent finds the address and fails to read it, so it never reaches the APIs.
- Having no catalog is no problem: many sites offer no API.
How to fix
Serve the file as application/linkset+json, with an entry for each API:
json
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [{ "href": "https://api.example.com/v1/openapi.json", "type": "application/json" }],
"service-doc": [{ "href": "https://example.com/docs/api" }]
}
]
}How we detect
In the agent-readiness tool alone, we ask for /.well-known/api-catalog at the page's origin as ArablyzerBot, where robots.txt allows, with Accept: application/linkset+json, application/json, and ask with it for an address no site has too. A 4xx, an HTML page in its place, or a site that answers that missing address with 2xx and whose file fails the test, means the site offers no catalog. We read a 2xx as JSON and ask for a non-empty linkset, an anchor on each entry (RFC 9264), and the type RFC 9727 requires.