Skip to content

The API catalog cannot be used

api-catalog-invalidminor
On this page

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.