API Catalog — /.well-known/api-catalog (RFC 9727) and Link headers
TL;DR
An API catalog is a file at /.well-known/api-catalog that lists a site's public APIs as a linkset (RFC 9264): for each API, where its machine-readable description (service-desc), its documentation (service-doc) and its status page live. RFC 9727 (IETF Standards Track, June 2025) fixes the path, the format and the media type application/linkset+json. A Link header with rel="api-catalog" points an agent to it from any page.
Explain Simply
A big office building has a directory board in the lobby: which company is on which floor. The API catalog is that board for a website's APIs, always hung in the same spot (/.well-known/api-catalog), so a visiting robot does not have to walk every corridor.
The file (RFC 9727 §4, Appendix A):
GET /.well-known/api-catalog
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"
{"linkset": [
{"anchor": "https://example.com/api",
"service-desc": [{"href": "https://example.com/openapi.json", "type": "application/json"}],
"service-doc": [{"href": "https://example.com/docs/api", "type": "text/html"}],
"status": [{"href": "https://example.com/api/health"}]}
]}The rules that matter:
- linkset is the sole top-level member and an array; each relation value is an array of objects with an href (RFC 9264 §4.2).
- The relations come from RFC 8631: service-desc (OpenAPI or another machine-readable description), service-doc (human documentation), service-meta (policies, terms), status (health). A short catalog can list APIs as item links instead, and a large one can link to further catalogs with api-catalog.
- The media type MUST be application/linkset+json. Another format (APIs.json, a bare OpenAPI file, your own JSON) is allowed only in addition, by content negotiation — never instead of the linkset.
- A HEAD request to the path returns a Link header with rel="api-catalog" (§2).
Link headers (RFC 8288) carry the same pointer on every page: Link: </.well-known/api-catalog>; rel="api-catalog". Only registered relations mean something to an agent — api-catalog, service-desc, service-doc, describedby, or an alternate in text/markdown. preconnect, preload and shortlink are browser and CMS hints; bare names such as mcp-server or agent-skills are not in the IANA registry.
⚡Why It Matters
An AI agent that has to call your API (to book, to check stock, to run a scan) needs to find its description first. Without a catalog it guesses URLs or reads your HTML docs. The catalog is one small file, it is an IETF standard rather than a vendor format, and it is cheap to keep current. A site with no public API does not need one — that is why the check is low severity.
🔍How CiteStat Checks
CiteStat makes two checks. Link headers: passes when the page's Link header has at least one registered agent relation (api-catalog, service-desc, service-doc, service-meta, describedby, or a text/markdown alternate); a header with only browser hints or unregistered names is a low finding. API catalog: fetches /.well-known/api-catalog (or the target of a Link rel="api-catalog"); passes on a valid linkset served as application/linkset+json that lists at least one API. Ad-hoc JSON, a linkset with no API links, or non-JSON is a medium finding; a valid linkset with the wrong media type is low. An HTML page at the path counts as no catalog.
CiteStat Score Impact
Two of the 9 core checks on the Agent Readiness card (score = core checks passed / 9 × 10). They do not change the headline SEO score.
Fix Difficulty
Editor: Hard | Developer: Easy | AI Agent: Medium