Document RFC 9727 API catalog discovery endpoint (#5291)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Anar Kafkas <anarkafkas@gmail.com>
Co-authored-by: Devin Logan <devinannlogan@gmail.com>

Author: 3 people

fern/products/docs/docs.yml

@@ -201,6 +201,9 @@ navigation:
       - page: MCP server
         path: ./pages/ai/mcp-server.mdx
         slug: mcp-server
+      - page: API catalog discovery
+        path: ./pages/ai/api-catalog.mdx
+        slug: api-catalog
       - section: Ask Fern
         slug: ask-fern
         contents:

fern/products/docs/pages/ai/api-catalog.mdx

@@ -0,0 +1,44 @@
+---
+title: API catalog discovery
+description: Fern docs sites expose a standards-based API catalog endpoint so AI agents, MCP clients, and API catalog crawlers can discover your APIs automatically.
+---
+
+Fern Docs sites implement [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) 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](/learn/docs/api-references/overview) navigation and advertised on every page via a [`Link`](https://www.rfc-editor.org/rfc/rfc8288) 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](https://buildwithfern.com/learn/.well-known/api-catalog):
+
+```bash
+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`).
+
+## Response format
+
+The endpoint returns a [Linkset document](https://www.rfc-editor.org/rfc/rfc9264) listing each visible API. Each entry contains:
+
+- **`anchor`** — the URL of the human-readable API Reference page
+- **`service-desc`** — the machine-readable [OpenAPI spec](/learn/docs/developer-tools/openapi-spec)
+- **`service-doc`** — the same reference page as the anchor
+
+```json title="Example response"
+{
+  "linkset": [
+    {
+      "anchor": "https://example.docs.com/api-reference",
+      "service-desc": [
+        {
+          "href": "https://example.docs.com/openapi.yaml?api=abc123",
+          "type": "application/yaml"
+        }
+      ],
+      "service-doc": [
+        {
+          "href": "https://example.docs.com/api-reference",
+          "type": "text/html"
+        }
+      ]
+    }
+  ]
+}
+```

fern/products/docs/pages/ai/overview.mdx

@@ -40,10 +40,11 @@ AI helps keep your documentation current. Fern Writer is a Slack-based technical
 
 ## Optimize for AI
 
-Your site is automatically optimized for AI tools and search engines. Fern hosts `llms.txt` and `llms-full.txt` files so LLMs can index your documentation efficiently, and serves Markdown instead of HTML to AI agents. These features reduce token consumption and help agents process your content faster.
+Your site is automatically optimized for AI tools and search engines. Fern hosts `llms.txt` and `llms-full.txt` files so LLMs can index your documentation efficiently, serves Markdown instead of HTML to AI agents, and exposes a standards-based API catalog for automated discovery. These features reduce token consumption and help agents process your content faster.
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="Markdown access" icon="file-code" href="/learn/docs/ai-features/markdown" />
   <Card title="`llms.txt`" icon="file-text" href="/learn/docs/ai-features/llms-txt" />
   <Card title="Agent directives" icon="compass" href="/learn/docs/ai-features/agent-directives" />
+  <Card title="API catalog discovery" icon="radar" href="/learn/docs/ai-features/api-catalog" />
 </CardGroup>

fern/products/docs/pages/api-references/overview.mdx

@@ -3,7 +3,7 @@ title: Overview of API References
 description: Understand how to generate, customize, and enhance API Reference documentation with Fern.
 ---
 
-Fern generates interactive API Reference documentation from an [OpenAPI specification](/learn/api-definitions/openapi/overview), [Fern Definition](/learn/api-definitions/ferndef/overview), or other API formats. Endpoints, type schemas, code snippets, and [AI-generated examples](/learn/docs/ai-features/ai-examples) are all populated automatically. Users can try requests directly from the docs with the [API Explorer](/learn/docs/api-references/api-explorer).
+Fern generates interactive API Reference documentation from an [OpenAPI specification](/learn/api-definitions/openapi/overview), [Fern Definition](/learn/api-definitions/ferndef/overview), or other API formats. Endpoints, type schemas, code snippets, and [AI-generated examples](/learn/docs/ai-features/ai-examples) are all populated automatically. Users can try requests directly from the docs with the [API Explorer](/learn/docs/api-references/api-explorer), and AI agents and crawlers can discover your APIs via the [API catalog](/learn/docs/ai-features/api-catalog) endpoint.
 
 ## Pick your API type
 

fern/products/docs/pages/changelog/2026-05-01.mdx

@@ -0,0 +1,9 @@
+---
+tags: ["ai"]
+---
+
+## API catalog discovery
+
+AI agents, MCP clients, and API catalog crawlers can now discover your APIs automatically. Every Fern Docs site exposes a standards-based ([RFC 9727](https://www.rfc-editor.org/rfc/rfc9727)) `/.well-known/api-catalog` endpoint generated from your visible API Reference navigation.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/ai-features/api-catalog">Read the docs</Button>