Document RFC 9727 API catalog discovery endpoint

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,60 @@
+---
+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. Every docs site automatically serves a `/.well-known/api-catalog` endpoint and advertises it via a [`Link`](https://www.rfc-editor.org/rfc/rfc8288) response header on every page.
+
+No configuration is required — the catalog is generated from your visible [API Reference](/learn/docs/api-references/overview) navigation.
+
+## How it works
+
+Every page response includes a `Link` header pointing to the catalog:
+
+```http
+Link: </.well-known/api-catalog>; rel="api-catalog"
+```
+
+A `GET` or `HEAD` request to `/.well-known/api-catalog` returns an [RFC 9264](https://www.rfc-editor.org/rfc/rfc9264) Linkset document (`application/linkset+json`) 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) (`/openapi.yaml?api=<id>`)
+- **`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"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Hidden API references (set with `hidden: true` or with all endpoints hidden) are excluded from the catalog.
+
+## Trying it out
+
+You can test the endpoint on any Fern docs site:
+
+```bash
+curl -s https://your-docs-site.com/.well-known/api-catalog | jq .
+```
+
+For sites with a basepath like `/docs`, the endpoint is at `/.well-known/api-catalog` under that basepath:
+
+```bash
+curl -s https://your-docs-site.com/docs/.well-known/api-catalog | jq .
+```

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={4}>
   <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/changelog/2026-05-01.mdx

@@ -0,0 +1,9 @@
+---
+tags: ["ai"]
+---
+
+## API catalog discovery
+
+Your docs site exposes an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) `/.well-known/api-catalog` endpoint and advertises it via `Link` response headers, enabling AI agents, MCP clients, and API catalog crawlers to discover your APIs automatically. The catalog is generated from your visible API Reference navigation and requires no configuration.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/ai-features/api-catalog">Read the docs</Button>