API catalog (RFC 9727): what the check tests and how to fix it

Weight 1. Looks for /.well-known/api-catalog as application/linkset+json with an entry that has an anchor and item, service-desc or service-doc links.

Agent Auth · Weight 1 in the w2agent Score

How common is it?

23% of 413 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

The audit requests /.well-known/api-catalog with Accept: application/linkset+json. The crawl accepts the response only if the status is 200, the media type is exactly application/linkset+json (parameters such as profile are ignored), and the body differs from what your server returns for a random path under /.well-known/, so a catch-all page is not mistaken for a catalog.

Then run() reads the body:

  • Fail 0: nothing accepted; or the body is not a JSON object with a linkset array; or no entry in the array qualifies.
  • Pass 100: at least one entry qualifies. The message gives the count.
  • Skip: replaces a fail when the public API check failed or was skipped. A pass is kept regardless.

An entry qualifies when it is an object with a string anchor and at least one of item, service-desc or service-doc as a non-empty array in which every element is an object with a string href.

The check does not test everything RFC 9727 asks for. It does not look at the profile parameter, the HEAD request that should return Link headers, or whether the href targets resolve.

Why it matters to agents

RFC 9727 (June 2025, Standards Track) gives publishers one well-known address from which a client can learn what APIs they offer, without searching the site. The catalog must be in Linkset format (application/linkset+json, RFC 9264) and must include hyperlinks to the API endpoints. It suggests adding metadata such as usage policies, version information and links to OpenAPI definitions. The service-desc relation points to a machine-readable description of an API and service-doc to human-readable documentation.

For an agent this replaces guessing paths like /api/ or /openapi.json. The standard is new, and the RFC says nothing about how many clients read it. Treat it as a low-cost way to make the API you already have easy to find, not as a known lever for traffic.

If you have no public API, there is nothing to list, and the check is skipped.

How to fix it

Only if you publish an API. Serve this at https://example.com/.well-known/api-catalog with Content-Type: application/linkset+json:

{
  "linkset": [
    {
      "anchor": "https://example.com/api/v1",
      "service-desc": [
        { "href": "https://example.com/openapi.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://example.com/developers", "type": "text/html" }
      ]
    }
  ]
}
  • One entry per API. anchor is the API's address; the links point to its description and documentation. This shape follows RFC 9727 appendix A.1.
  • RFC 9727 recommends a profile parameter on the content type, profile="https://www.rfc-editor.org/info/rfc9727", and a response to HEAD requests with a Link header. The audit does not require either, but add them when you can.
  • Serve the file from a static path. Do not let a catch-all route answer /.well-known/api-catalog with an HTML page.
  • Point service-desc at an OpenAPI document and service-doc at your developer portal.
  • If your APIs run on several domains, RFC 9727 section 5.1 recommends publishing the catalog on each, with the others redirecting to one canonical copy.

Check with curl -si -H 'Accept: application/linkset+json' https://example.com/.well-known/api-catalog and confirm the status and Content-Type.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →