diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index a94479cf20..f362f8d2bc 100644 --- a/fern/products/docs/docs.yml +++ b/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: diff --git a/fern/products/docs/pages/ai/api-catalog.mdx b/fern/products/docs/pages/ai/api-catalog.mdx new file mode 100644 index 0000000000..d0c00efd7a --- /dev/null +++ b/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" + } + ] + } + ] +} +``` diff --git a/fern/products/docs/pages/ai/overview.mdx b/fern/products/docs/pages/ai/overview.mdx index 5f1f393dd1..f2deb15350 100644 --- a/fern/products/docs/pages/ai/overview.mdx +++ b/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. - + + diff --git a/fern/products/docs/pages/api-references/overview.mdx b/fern/products/docs/pages/api-references/overview.mdx index 458e253a19..a63823ab80 100644 --- a/fern/products/docs/pages/api-references/overview.mdx +++ b/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 diff --git a/fern/products/docs/pages/changelog/2026-05-01.mdx b/fern/products/docs/pages/changelog/2026-05-01.mdx new file mode 100644 index 0000000000..63fdc6fd32 --- /dev/null +++ b/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. + +