API catalog (RFC 9727): one file that lists every API you have

Your APIs are on a docs page a machine cannot find

Most companies with an API document it on a developer portal for people to read. An agent looking for a programmatic way to do something on your domain cannot use that page: it does not know the URL, cannot parse the navigation reliably, and has no way to tell an OpenAPI file from a blog post about one. So it scrapes, or it gives up.

RFC 9727, published in 2025, fixes the discovery step. It registers a well-known URI, /.well-known/api-catalog, and a link relation, api-catalog, and says the resource there is a linkset (RFC 9264) enumerating the publisher's APIs with links to their descriptions, documentation and status. The RFC's stated purpose is to help automated clients discover and use APIs; it is on Cloudflare's readiness list under Protocol Discovery and in Qomvia's protocols dimension.

The format

A linkset is a JSON object with a linkset array. Each entry has an anchor (the API's base URL) and one or more link relations pointing at resources about that API. The relations the RFC recommends are service-desc for the machine-readable description (an OpenAPI document, typically), service-doc for human documentation, service-meta for policies and terms, and status for a health or status page.

{
  "linkset": [
    {
      "anchor": "https://api.brand.ch/v1/",
      "service-desc": [
        { "href": "https://api.brand.ch/v1/openapi.json", "type": "application/openapi+json" }
      ],
      "service-doc": [
        { "href": "https://developers.brand.ch/v1/", "type": "text/html" }
      ],
      "service-meta": [
        { "href": "https://developers.brand.ch/terms", "type": "text/html" }
      ],
      "status": [
        { "href": "https://status.brand.ch/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://api.brand.ch/mcp",
      "service-desc": [
        { "href": "https://www.brand.ch/.well-known/mcp.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://www.brand.ch/mcp", "type": "text/html" }
      ]
    }
  ]
}

• Serve it with Content-Type: application/linkset+json. The RFC also allows application/linkset (the header-style text format); JSON is what clients parse most easily.
• One entry per API base URL. A public REST API, an MCP server and a product feed can each be an entry; the anchor is what the agent will call.
• Add Link: </.well-known/api-catalog>; rel="api-catalog" to HTML responses so clients that start from your homepage find it without knowing the well-known path. The Link header article has the config.
• Keep it under version control next to the OpenAPI files it points at, and regenerate both together.

The catalog is a map, not the territory

RFC 9727 deliberately says nothing about what the APIs do or how to authenticate against them; that is the job of the resources it links. So a catalog is only as useful as its service-desc targets. An OpenAPI document with real operation descriptions, example responses and a securitySchemes block is what the agent needs next. Qomvia's Machine-readable data surface check under Discovery looks for that OpenAPI file (or a feed) separately from the catalog, so both are scored.

If the API requires sign-in, the catalog is also where the OAuth discovery metadata should be reachable from, either through service-meta or through the OpenAPI security scheme.

What Qomvia checks

API catalog (RFC 9727) under Agent protocols fetches /.well-known/api-catalog and passes on a 200. It is 1 point. The check is binary because the RFC is young and adoption is still rare, which means a catalog today is a visible differentiator for any site that has an API at all.

Questions

We have no public API. Should we publish an empty catalog?

No. Publish one when you have at least one machine-readable endpoint: a product feed, an MCP server, or a read-only REST API. An empty linkset tells agents nothing.

Is the catalog the same as an OpenAPI file?

No. OpenAPI describes one API's operations. The catalog lists which APIs exist and where their OpenAPI files, docs and status pages are.

Does the catalog have to be at the apex domain?

The well-known path is per host. Publish it on the host agents will start from, usually the www or apex site, and have it point at the api subdomain.