--- title: "How to expose OpenAPI for docs: Agent Ready HTML" description: "Make the API contract findable by link from the docs agents already read. 6 sourced facts, 6 steps and a check you can run in the viewer." canonical: https://agentreadyhtml.com/guides/expose-openapi-for-docs/ site: "Agent Ready HTML" last_updated: 2026-11-04 section: "Guides" --- # How to expose OpenAPI for docs: Agent Ready HTML > Make the API contract findable by link from the docs agents already read. 6 sourced facts, 6 steps and a check you can run in the viewer. Source: https://agentreadyhtml.com/guides/expose-openapi-for-docs/ Site: Agent Ready HTML Last reviewed: 2026-11-04 # How to expose OpenAPI for docs In short Publish the OpenAPI file at a stable URL and link it from the pages agents already read: the docs home page, the API reference and llms.txt. Agents fetched openapi.json by a link in 97 percent of attributed cases, and in only 21 percent of runs on sites that shipped one. An agent does not guess where your API contract lives. If the file is linked from the docs it reads, it can use it; if not, it mostly never finds it. ## What the evidence says - On seven sites that shipped openapi.json, agents fetched it in 112 of 541 runs, 21 percent. \[primary source\] [source](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 4 November 2026. - 97 percent of attributed openapi.json fetches arrived through a link rather than a guessed path. \[vendor claim, 2026-10-19\] [source](https://ora.ai/blog/agentready-launch?utm_source=agentreadyhtml.com&utm_medium=referral&utm_campaign=guide), read 4 November 2026. - Fern links the standalone OpenAPI spec from llms.txt for sites with API endpoints. \[primary source\] [source](https://buildwithfern.com/learn/docs/ai-features/llms-txt), read 4 November 2026. - Mintlify lists OpenAPI and AsyncAPI spec links in llms.txt and can advertise an API catalog in its Link header. \[primary source\] [source](https://www.mintlify.com/docs/ai/llmstxt), read 4 November 2026. - ReadMe includes servers and security schemes in the markdown of API Reference intro pages when the OpenAPI definition is visible. \[primary source\] [source](https://docs.readme.com/main/changelog/upgraded-llms-txt), read 4 November 2026. - In the crawl, 29 of 8,816 home pages that answered 200 linked an OpenAPI file (edition 2026-11-04). \[primary source\] [source](https://agentreadyhtml.com/data/), read 4 November 2026. ## Steps 1. Publish the contract at a stable, short URL such as /openapi.json. 2. Link it from the docs home page and from the API reference page with a normal anchor. 3. List it in llms.txt under the docs section. Fern and Mintlify both do this for sites with API endpoints. 4. Advertise it in an HTTP Link header with rel="service-desc" or a link element in the head, so a client that reads headers finds it. 5. Keep the file in step with the API: a stale contract is worse than none. 6. Run the viewer on the docs home page: the OpenAPI flag reads found when an anchor or a service-desc relation points at the file. Header and link element Link: ; rel="service-desc"; type="application/json" ## Check the result On 4 November 2026 the viewer read a service-desc link relation in the response headers of ora.ai pointing at an OpenAPI file; that is the pattern above. Open the [viewer](https://agentreadyhtml.com/viewer/) to run it on your own URL. Related: [all guides](https://agentreadyhtml.com/guides/), [initial HTML](https://agentreadyhtml.com/initial-html/), [llms.txt](https://agentreadyhtml.com/llms-txt/). ## Sources 1. [Vercel and Ora: Make your site readable by AI agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents) https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents, read 4 November 2026 2. [Ora: AgentReady launch post, findings 01 to 04](https://ora.ai/blog/agentready-launch?utm_source=agentreadyhtml.com&utm_medium=referral&utm_campaign=guide) https://ora.ai/blog/agentready-launch, read 4 November 2026 3. [Fern docs: llms.txt](https://buildwithfern.com/learn/docs/ai-features/llms-txt) https://buildwithfern.com/learn/docs/ai-features/llms-txt, read 4 November 2026 4. [Mintlify docs: llms.txt](https://www.mintlify.com/docs/ai/llmstxt) https://www.mintlify.com/docs/ai/llmstxt, read 4 November 2026 5. [ReadMe changelog: Upgraded LLMs.txt](https://docs.readme.com/main/changelog/upgraded-llms-txt) https://docs.readme.com/main/changelog/upgraded-llms-txt, read 4 November 2026 6. [The crawl dataset (this site)](https://agentreadyhtml.com/data/) https://agentreadyhtml.com/data/, read 4 November 2026 Last reviewed 4 November 2026 Edition Crawl 2026-11-04 Page updated 2026-11-04 Method How the viewer reads a page, how a file is graded and how a platform is scored: [the method page](https://agentreadyhtml.com/method/). **Check it** Run the [viewer](https://agentreadyhtml.com/viewer/) after each step.