Document RFC 9727 API catalog discovery endpoint#5291
Merged
Conversation
Co-Authored-By: Anar Kafkas <anarkafkas@gmail.com>
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| 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. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'RFC' has no definition.
| 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: |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'RFC' has no definition.
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'RFC' has no definition.
Contributor
|
🌿 Preview your docs: https://fern-preview-devin-1777630596-api-catalog-docs.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
Co-Authored-By: Anar Kafkas <anarkafkas@gmail.com>
devalog
approved these changes
May 1, 2026
| 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. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'RFC' has no definition.
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'RFC' has no definition.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the RFC 9727
/.well-known/api-catalogdiscovery endpoint andLinkresponse headers added in fern-platform#10044.Changes:
fern/products/docs/pages/ai/api-catalog.mdxcovering how the feature works, the Linkset response format, and how to test itReview & Testing Checklist for Human
/learn/docs/ai-features/api-catalogin the preview deploymentNotes
Kept the page concise since this is a small, zero-config feature. The RFC acronym Vale suggestion is intentionally left as-is — RFC is widely understood and used throughout the docs without definition.
Link to Devin session: https://app.devin.ai/sessions/67ec4e09ff754ba5a9f7486df2f94d88
Requested by: @kafkas