Conversation
The api-catalog endpoint is gated on the download-spec contextual option, but no page said so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
This branch was successfully deployed
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
1 participant
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.
The api-catalog endpoint is gated on the download-spec contextual option, but no page said so.
Documentation changes
api-playground/openapi-setup.mdx: in "Let visitors download your spec", added that enablingdownload-specalso publishes an RFC 9727 API catalog at/.well-known/api-catalog, that the endpoint returns 404 without it, and that it's auth-gated on authenticated projects.ai/llmstxt.mdx: theLinkheader bullet now links the API catalog to that section and notes it's served only whendownload-specis enabled.help-center/register-external-mcp-server-in-discovery.mdx: noted the catalog is only served after opting into spec downloads.Rationale
/.well-known/api-catalogis gated ondownload-specincontextual.options(minthasDownloadSpecOptIn, added in mintlify/mint#8354), but no page said so. The llms.txt page and help-center article implied the catalog is generated automatically from any OpenAPI spec indocs.json, so users seeing the advertised link 404 had no way to find the fix.Verification
mint broken-links: no broken links.Areas of uncertainty
Linkheader currently advertisesapi-catalogon every site regardless of opt-in. That's being handled separately in mint; if that behavior changes (for example, serving an empty catalog instead of a 404), the "returns a 404" sentence inopenapi-setup.mdxwill need an update.Closes
For Reviewers
When reviewing documentation PRs, please consider:
✅ Technical accuracy
✅ Clarity and completeness
✅ User experience
Note
Low Risk
Documentation-only updates with no product or security behavior changes.
Overview
Documents that
/.well-known/api-catalogis only available whendownload-specis enabled incontextual.options, so readers understand why the catalog might 404 despite theLinkheader.The OpenAPI setup page now explains that opting in also publishes an RFC 9727 catalog for agent discovery, that the endpoint returns 404 without
download-spec, and that auth/userAuth sites restrict catalog access like spec downloads. The llms.txt page ties the advertised API catalog in theLinkheader to that section and the same opt-in requirement. The external MCP help article clarifies the catalog is not automatic from OpenAPI indocs.jsonalone—it follows the spec-download opt-in.Reviewed by Cursor Bugbot for commit 0461db6. Bugbot is set up for automated code reviews on this repo. Configure here.