API Catalog (RFC 9727): How AI Agents Find Your API

Short answer: an API catalog is a JSON file at /.well-known/api-catalog that lists a site's public APIs: for each API, where its machine-readable description (usually OpenAPI), its documentation and its status page live. The standard is IETF RFC 9727 (June 2025). The file must be a linkset, served with Content-Type: application/linkset+json. Add Link: </.well-known/api-catalog>; rel="api-catalog" to your page responses so agents find it.

Why AI agents need a catalog

An AI agent reads your page to answer a question. But when a user asks it to do something — book a slot, check stock, run a scan — it has to call an API. To call an API it needs the description: which endpoints, which parameters, which authentication. Without a catalog, the agent guesses URLs such as /api/docs or reads your HTML documentation. RFC 9727 puts that map in one fixed place, as robots.txt does for crawlers and llms.txt does for language models.

What the file looks like

This is the catalog of developers.cloudflare.com, fetched on 22 October 2026:

GET /.well-known/api-catalog
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

{"linkset": [
  {"anchor": "https://developers.cloudflare.com/api/",
   "service-desc": [{"href": "https://developers.cloudflare.com/openapi.json", "type": "application/json"}],
   "service-doc":  [{"href": "https://developers.cloudflare.com/api/", "type": "text/html"}],
   "status":       [{"href": "https://www.cloudflarestatus.com/api/v2/status.json", "type": "application/json"}]}
]}

The rules in RFC 9727 and RFC 9264 (the linkset format):

• linkset is the sole top-level member, and an array. Each entry has an anchor (the API's URL) and its relations.
• Each relation's value is an array of objects with an href, even when there is one link.
• 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 with item only; a large one points to sub-catalogs with api-catalog.
• The media type must be application/linkset+json. APIs.json, a bare OpenAPI file or your own JSON may be served in addition through content negotiation, never instead of the linkset.
• A HEAD request to the path must return a Link header with rel="api-catalog".

Link headers: only registered relations mean anything

A Link header (RFC 8288) tells an agent about related resources without parsing HTML. But many pages already send Link headers for other reasons: WordPress sends rel="https://api.w.org/" and shortlink, themes send preconnect to font servers, frameworks send rows of preload. Those are browser hints. An agent looks for relations in the IANA registry: api-catalog, service-desc, service-doc, describedby, or an alternate with type="text/markdown" (see markdown negotiation). Made-up names such as mcp-server or agent-skills are not in the registry.

We checked 8 sites

On 22 October 2026 we ran the CiteStat scan's own code (packages/core/api-catalog.ts) on the home page and /.well-known/api-catalog of 8 sites:

Site	Link header for agents	API catalog
developers.cloudflare.com	service-doc, describedby, alternate	Pass — OpenAPI + docs + status
blog.cloudflare.com	api-catalog	Pass — 3 APIs, one an MCP server
vercel.com	api-catalog	Pass — 1 API (item + OpenAPI + status)
docs.stripe.com	service-meta	None (404)
docs.claude.com	alternate (markdown)	None — the path returns an HTML page
github.com	none	None (404)
erpfit.com	none	None (404)
citestat.com (before the fix)	api-catalog (+ 2 unregistered names)	Wrong — ad-hoc JSON, application/json

Two things stand out. First, Vercel lists api.vercel.com twice: once as an item, once as a described anchor. It is still one API — the scan counts distinct URLs, not entries. Second, docs.claude.com answers any unknown path with a 200 HTML page. A checker that only looks at the 200 would say "catalog found"; the scan treats an HTML page as no catalog.

Our own mistake

Until 22 October 2026, CiteStat's own /.well-known/api-catalog was ad-hoc JSON ({"apis": [...]}) served as application/json. Not a linkset, wrong media type. Worse, our scan accepted any JSON at that path and called it "RFC 9727 compliant" — and accepted any Link header, even one with only preconnect. We fixed both: the catalog is now a valid linkset (API docs in HTML and markdown, plus the status endpoint), the Link header carries only registered relations, and an automated test runs the scan's judge on our own catalog. The catalog has no service-desc because we do not publish an OpenAPI file yet — a catalog should not point at a file that does not exist.

How to publish a catalog in three steps

1. Write the file. One entry per API: anchor is the API's base URL; add service-desc if you have OpenAPI, service-doc for the docs, status if you have a status endpoint.
2. Serve the right media type. In nginx the .json extension would set the wrong Content-Type, so set it explicitly:

   location = /.well-known/api-catalog {
     types { }
     default_type application/linkset+json;
     add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
     alias /var/www/api-catalog.json;
   }

3. Add the Link header </.well-known/api-catalog>; rel="api-catalog" to your home page response (or every page).

No public API? Skip all of this. An empty catalog helps no agent.

What CiteStat checks

On the Agent Readiness card the scan makes two checks. Link headers pass when at least one registered agent relation is present. The API catalog passes when /.well-known/api-catalog (or the target of rel="api-catalog") is a valid linkset with the right media type and at least one API. Ad-hoc JSON is a medium finding; the wrong media type is low. Neither changes the headline SEO score. The free plan gives 10 scans a day; if you look after several sites, see pricing: Pro is 500,000₫/month (excl. VAT) for 100 scans a day.

Frequently asked questions

Does a site without an API need an API catalog?

No. A catalog lists public APIs. A site with no API has nothing to list, and an empty or invented catalog is worse than none. That is why the CiteStat scan reports a missing catalog only as a low finding.

Can I put my OpenAPI file at /.well-known/api-catalog?

Not instead of the linkset. RFC 9727 requires the catalog in linkset format (application/linkset+json). The OpenAPI file lives at its own URL and the catalog points to it with a service-desc link. Other formats may only be offered in addition, through content negotiation.

Which Link headers help AI agents?

Relations registered with IANA that an agent understands: api-catalog, service-desc, service-doc, service-meta, describedby, and an alternate in text/markdown. preconnect, preload and shortlink are browser hints. Made-up names such as mcp-server are not in the registry, so an agent does not know what they mean.

Does an API catalog improve Google rankings?

No Google document says so. The catalog is for agents and tools that need to call your API, not a ranking signal. The CiteStat scan counts it on the Agent Readiness card and leaves the headline SEO score unchanged.

Sources: RFC 9727 (IETF, June 2025) · RFC 9264 (linkset, July 2022) · RFC 8631 (service-desc, service-doc) · IANA Link Relations (updated 12 June 2026). Data for the 8 sites: fetched 22 October 2026.