API catalog discovery

Fern Docs sites implement RFC 9727 to let AI agents, MCP clients, and API catalog crawlers discover your APIs without scraping HTML. The catalog is generated from your visible API Reference navigation and advertised on every page via a Link response header — no configuration required. References hidden via hidden: true (or with all endpoints hidden) are excluded.

Your API catalog is available at your-documentation-site.com/.well-known/api-catalog. For example, this site’s catalog is at buildwithfern.com/learn/.well-known/api-catalog:

$
curl -s https://buildwithfern.com/learn/.well-known/api-catalog | jq .

For sites with a basepath like /docs, the catalog lives under that basepath (e.g. https://example.com/docs/.well-known/api-catalog).

Visibility

The catalog mirrors what the viewer can see:

• Sites with authentication configured return an empty catalog ({"linkset": []}) to unauthenticated requests.
• API references hidden from the viewer through role-based access control are excluded.
• References hidden via hidden: true (or with all endpoints hidden) are excluded.

Response format

The endpoint returns a Linkset document listing each visible API. Each entry contains:

• anchor — the URL of the human-readable API Reference page
• service-desc — the machine-readable OpenAPI spec
• service-doc — the same reference page as the anchor

1
{
2
  "linkset": [
3
    {
4
      "anchor": "https://example.docs.com/api-reference",
5
      "service-desc": [
6
        {
7
          "href": "https://example.docs.com/openapi.yaml?api=abc123",
8
          "type": "application/yaml"
9
        }
10
      ],
11
      "service-doc": [
12
        {
13
          "href": "https://example.docs.com/api-reference",
14
          "type": "text/html"
15
        }
16
      ]
17
    }
18
  ]
19
}