.well-known/api-catalog

What is api-catalog?

A document at https://yoursite.com/.well-known/api-catalog (note: no .json extension, the RFC specifies the bare name) that lists your organization's public APIs in the Linkset format, with links to each API's specification and documentation. An agent does one GET request and gets a complete machine-readable map of your API surface, no HTML crawling, no guessing endpoint paths.

Why AI agents need it

It's the agent equivalent of what robots.txt and sitemap.xml are for search: a known place with a machine-readable answer. Agents, SDK generators, and API tooling can discover your OpenAPI specs and documentation automatically instead of relying on what happened to be in their training data.

The business value for you

If you have a public API, it becomes discoverable through a full IETF standard. If you don't, the placeholder we ship is still valuable: a valid empty Linkset with a comment explaining that no public API is advertised. That is a truthful machine-readable answer, far better than the common failure mode where a well-known path returns your homepage HTML with a 200 status, which effectively lies to every agent that asks.

How it came to be

RFC 9727 was published by the IETF in June 2025, defining the api-catalog well-known URI and link relation. It builds on RFC 9264 (Linkset, published 2022) for the response body. This is ratified standards-track work, the strongest authority class any file in the package can have.

Sources: IETF RFC 9727, api-catalog • IETF RFC 9264, Linkset

Adoption

Strikingly early. A May 2026 survey by API Evangelist found only four providers serving a valid RFC 9727 Linkset at the well-known path, and, tellingly, 68 sites that returned a 200 with HTML instead, breaking the standard they appeared to support. Cloudflare's agent-readiness analysis similarly counted API Catalogs and MCP Server Cards together on fewer than 15 sites in its dataset. A published RFC with almost no correct implementations is exactly where early movers stand out.

Sources: API Evangelist, Four providers publishing a well-known API catalog (May 2026) • Cloudflare, Introducing the Agent Readiness score (2026)

The technical reality

The details are where implementations fail: the file must be named exactly api-catalog with no extension, served as application/linkset+json (agents can reject plain application/json), and structured per RFC 9264 with correct link relations. For customers without a public REST API, we emit a valid empty Linkset plus a _comment field explaining the placeholder, with a corresponding note in your installation instructions. For customers with an API, the catalog is populated from your real endpoints.

What happens if you skip it

Agents that check the standard path get a 404, or worse, your homepage pretending to be a catalog. Either way, your API surface (or its documented absence) stays illegible to the tooling that increasingly asks the question automatically.