--- title: "AR-ACT-02: OpenAPI contract | Agent Ready Checklist" description: "AR-ACT-02 (SHOULD, Act layer): OpenAPI contract. What it asks, the evidence, the command that verifies it and the fix on 19 platforms." canonical: https://agentreadychecklist.com/checklist/ar-act-02 site: "Agent Ready Checklist" last_updated: 2026-11-05 section: "Checklist" --- # AR-ACT-02: OpenAPI contract | Agent Ready Checklist > AR-ACT-02 (SHOULD, Act layer): OpenAPI contract. What it asks, the evidence, the command that verifies it and the fix on 19 platforms. Source: https://agentreadychecklist.com/checklist/ar-act-02 Site: Agent Ready Checklist Last reviewed: 2026-11-05 Agent endpoints: https://agentreadychecklist.com/llms.txt (index), https://agentreadychecklist.com/openapi.json (API), https://agentreadychecklist.com/mcp (MCP server), https://agentreadychecklist.com/ask (search) Access: https://agentreadychecklist.com/auth.md (no key). Pricing: https://agentreadychecklist.com/pricing.md (free). # AR-ACT-02: OpenAPI contract AR-ACT-02 is a SHOULD on the act layer: Describe the public API with a machine-readable OpenAPI contract. 19 of 19 platforms have a recipe below, 8 of them workarounds. The kit check openapi tests it with one command. Ora reads it with the check openapi-spec. 3 cited facts back it, 1 labelled as a vendor claim. ## The requirement Identifier AR-ACT-02 Level SHOULD Layer Act Applies to products with a public API Checked by Ora, matched on this site, Cloudflare apiCatalog, is-agentic.com, Verify Kit openapi Ora check [openapi-spec](#ora) The statement Describe the public API with a machine-readable OpenAPI contract. ## Why - Ora's lab found (published 2026-10-21): on the seven sites that ship an openapi.json, agents fetched it in 21% of runs (112 of 541), and 97% of those fetches came through a link.vendor claim, 2026-10-21: [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md), read 2026-11-04 - The spec lists operation IDs, typed responses and errors, /v1/ versioning and documented rate limits as best practice.primary source: [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md), read 2026-11-04 - RFC 9727 api-catalog at /.well-known/api-catalog links an API to its OpenAPI file with the service-desc relation.primary source, 2025-06-01: [rfc-editor.org/rfc/rfc9727](https://www.rfc-editor.org/rfc/rfc9727), read 2026-11-04 ## How to verify ### [OpenAPI linked and valid](https://agentreadychecklist.com/kit/openapi/) ```bash curl -fsSL https://agentreadychecklist.com/kit/verify.sh | bash -s -- https://example.com --only=openapi ``` Finds an OpenAPI URL from a home page link, a Link rel=service-desc header, /.well-known/api-catalog or /openapi.json, fetches it and checks it parses with an openapi field and a paths object. **It cannot prove:** Does not lint the contract or call any operation. ### The one-line version curl -s | jq -e ".openapi and .paths". ## Verify with Ora One check in Ora's catalogue (contract 1.38.0, read 2026-11-05) read this row. Each entry says what the check looks at and why this page lists it. - `openapi-spec` OpenAPI spec published Looks for a published OpenAPI spec. It carries 7 points, the most of any check in the Access layer. Access, 7 points, required; catalogue applicability domain-only. Listed because: same name, `openapi`. ### Run just these checks ```bash curl -s -X POST https://ora.ai/api/scan/checks -H 'content-type: application/json' -d '{"url":"https://example.com","checkIds":["openapi-spec"]}' ``` This calls the endpoint Ora documents for re-verifying a fix. It sends no cache, returns a result for each id and no total score, and spends one scan from the daily budget. Replace the URL with yours. [How to re-verify one fix](https://agentreadychecklist.com/guides/re-verify-one-fix-with-ora/). ### Or audit the whole site ```bash npx ax@0.10 audit https://example.com --min-score 70 ``` ### Related checks This check reads something near the row but asks for more than the row does. A site that meets the row can score nothing or lose points on it, so it is not counted as a test of the row and is left out of the command above. - `api-catalog-rfc9727` API catalog (RFC 9727) Looks for an API catalog at /.well-known/api-catalog (RFC 9727). That is a separate file from the OpenAPI contract the row asks for, so a site that meets the row can score nothing here. Access, 2 points, bonus, required; catalogue applicability domain-only. Exit code 1 means the score is below the number you passed, so the same line gates a deploy: [the CI recipe](https://agentreadychecklist.com/guides/gate-deploys-on-agent-readiness-in-ci/). [Why this site recommends Ora, and where it falls short](https://agentreadychecklist.com/verify-with-ora/). ## In the crawl This row has one crawl rate. Each panel splits the 2026-11-04 crawl into ten bands of 1,000 ranks, on a 0 to 100 percent scale. OpenAPI linked from the home page or served at /openapi.json 0.5% overall Reachable sites in the Tranco top 10,000 on which the check ran, 2026-11-04. Left is ranks 1 to 1,000. Numbers behind the chart | Rate | 1 to 1,000 | 1,001 to 2,000 | 2,001 to 3,000 | 3,001 to 4,000 | 4,001 to 5,000 | 5,001 to 6,000 | 6,001 to 7,000 | 7,001 to 8,000 | 8,001 to 9,000 | 9,001 to 10,000 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | OpenAPI linked from the home page or served at /openapi.json | 1% | 1% | 0% | 1% | 0% | 1% | 0% | 0% | 0% | 0% | ## Fix it on your platform ### Next.js (App Router)recipe Commit openapi.json to public/ (served at /openapi.json) or return it from app/openapi.json/route.ts. Link it from the footer and from llms.txt. Next.js 16.x (npm latest 16.4.5, read 2026-11-04); docs at nextjs.org/docs/app. Read 2026-11-04. [nextjs.org/docs/app/api-reference/file-conventions/public-folder](https://nextjs.org/docs/app/api-reference/file-conventions/public-folder). [All Next.js (App Router) recipes](https://agentreadychecklist.com/platforms/nextjs-app-router/#ar-act-02) ### Astrorecipe Copy openapi.json into public/ so it is served at /openapi.json; link it from the footer and llms.txt. Astro 7.x (npm latest astro 7.4.5, @astrojs/sitemap 3.7.4, read 2026-11-04). Read 2026-11-04. [docs.astro.build/en/basics/project-structure/](https://docs.astro.build/en/basics/project-structure/). [All Astro recipes](https://agentreadychecklist.com/platforms/astro/#ar-act-02) ### Nuxtrecipe Put openapi.json in public/ (served from the root) and link it from the footer. Nuxt 4.x (npm latest nuxt 4.6.4, @nuxtjs/robots 7.0.2, @nuxtjs/sitemap 9.1.0, read 2026-11-04). Read 2026-11-04. [nuxt.com/docs/guide/directory-structure/public](https://nuxt.com/docs/guide/directory-structure/public). [All Nuxt recipes](https://agentreadychecklist.com/platforms/nuxt/#ar-act-02) ### SvelteKitrecipe Put openapi.json in static/ (served at /openapi.json) and link it. SvelteKit (npm latest @sveltejs/kit 3.1.1, read 2026-11-04); docs at svelte.dev/docs/kit. Read 2026-11-04. [svelte.dev/docs/kit/project-structure](https://svelte.dev/docs/kit/project-structure). [All SvelteKit recipes](https://agentreadychecklist.com/platforms/sveltekit/#ar-act-02) ### Remix and React Router (framework mode)recipe Place openapi.json in public/ or return it from a resource route loader with Response.json(spec). React Router framework mode (npm latest react-router 8.5.1; Remix v2 @remix-run/node 2.17.5, read 2026-11-04); docs at reactrouter.com. Read 2026-11-04. [reactrouter.com/how-to/resource-routes](https://reactrouter.com/how-to/resource-routes). [All Remix and React Router (framework mode) recipes](https://agentreadychecklist.com/platforms/remix-react-router/#ar-act-02) ### Plain static hosting (Netlify, Vercel static, Cloudflare Pages, GitHub Pages, S3 and CloudFront)recipe Upload openapi.json to the root and link it; on Netlify or Pages set Access-Control-Allow-Origin: \* for it in \_headers so browser-based tools can read it. Host documentation as published on 2026-11-04 (no version numbers; config files \_headers, \_redirects, vercel.json, 404.html). Read 2026-11-04. [docs.netlify.com/manage/routing/headers/](https://docs.netlify.com/manage/routing/headers/). [All Plain static hosting (Netlify, Vercel static, Cloudflare Pages, GitHub Pages, S3 and CloudFront) recipes](https://agentreadychecklist.com/platforms/static-hosting/#ar-act-02) ### WordPress and Elementorrecipe Upload openapi.json to the web root or expose it from a custom REST route registered with `register_rest_route()`; link it from the footer. /wp-json/ alone is JSON Schema, not OpenAPI. WordPress 7.1.4 (core release from the version-check API), Elementor 4.3.6 (plugin directory, updated 2026-11-02), Yoast SEO 28.8 noted for llms.txt; docs read 2026-11-04. Read 2026-11-04. [developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/). [All WordPress and Elementor recipes](https://agentreadychecklist.com/platforms/wordpress-elementor/#ar-act-02) ### Shopify (Online Store 2.0 themes)workaround Serve openapi.json from your API host or through an app proxy (`[app_proxy] prefix = "apps" subpath = "api"` in shopify.app.toml maps /apps/api/\* to your app) and link it from the footer. Hosted SaaS, Online Store 2.0 Liquid themes, docs read 2026-11-04; storefront behaviour probed live on one Shopify store the same day. Read 2026-11-04. [shopify.dev/docs/apps/build/online-store/app-proxies](https://shopify.dev/docs/apps/build/online-store/app-proxies). [All Shopify (Online Store 2.0 themes) recipes](https://agentreadychecklist.com/platforms/shopify/#ar-act-02) ### Webflowworkaround Deploy a small Webflow Cloud app (Next.js or Astro) connected to the site that returns openapi.json, or host it on your API domain, and link it from the footer. Hosted SaaS, help center articles read 2026-11-04 (updated dates 2024-10-14 to 2026-10-29). Read 2026-11-04. [help.webflow.com/hc/en-us/articles/40846212086035-Webflow-Cloud-overview](https://help.webflow.com/hc/en-us/articles/40846212086035-Webflow-Cloud-overview). [All Webflow recipes](https://agentreadychecklist.com/platforms/webflow/#ar-act-02) ### Framerrecipe Upload openapi.json as a Static File at path / and link it from the footer. Hosted SaaS, help articles read 2026-11-04 (marked updated 2026-09-15). Read 2026-11-04. [framer.com/help/articles/static-files/](https://www.framer.com/help/articles/static-files/). [All Framer recipes](https://agentreadychecklist.com/platforms/framer/#ar-act-02) ### Wix (Wix Editor and Wix Studio)workaround Host openapi.json on your API domain and link it from the footer and from the Wix llms.txt. Hosted SaaS, help center read 2026-11-04. Read 2026-11-04. [support.wix.com/en/article/understanding-your-sites-llms-txt-file](https://support.wix.com/en/article/understanding-your-sites-llms-txt-file). [All Wix (Wix Editor and Wix Studio) recipes](https://agentreadychecklist.com/platforms/wix/#ar-act-02) ### Squarespace (version 7.1)workaround Host openapi.json on your API domain and link it from the footer and llms.txt. Hosted SaaS, version 7.1 sites, help center read 2026-11-04 (articles updated 2026-07-17 to 2026-11-03). Read 2026-11-04. [support.squarespace.com/hc/en-us/articles/47434125611277-Create-an-llms-txt-file (the article needs a Squarespace sign-in to read)](https://support.squarespace.com/hc/en-us/articles/47434125611277-Create-an-llms-txt-file). [All Squarespace (version 7.1) recipes](https://agentreadychecklist.com/platforms/squarespace/#ar-act-02) ### HubSpot CMS (Content Hub)workaround Upload openapi.json to the file manager and redirect /openapi.json to it, or host it on your API domain; link it from the footer. Hosted SaaS, Content Hub, knowledge base and developer docs read 2026-11-04. Read 2026-11-04. [developers.hubspot.com/docs/cms/start-building/features/storage/file-manager](https://developers.hubspot.com/docs/cms/start-building/features/storage/file-manager). [All HubSpot CMS (Content Hub) recipes](https://agentreadychecklist.com/platforms/hubspot-cms/#ar-act-02) ### Docusaurusrecipe Place the contract at static/openapi.json and link it from the footer and llms.txt. 3.10.2 (npm @docusaurus/core latest, read 2026-11-04). Read 2026-11-04. [docusaurus.io/docs/static-assets](https://docusaurus.io/docs/static-assets). [All Docusaurus recipes](https://agentreadychecklist.com/platforms/docusaurus/#ar-act-02) ### Mintlifyrecipe Commit openapi.json and reference it in docs.json ("openapi": "openapi.json"); add "download-spec" to contextual.options so readers and agents can fetch it. Hosted SaaS, docs read 2026-11-04. Read 2026-11-04. [mintlify.com/docs/api-playground/openapi-setup](https://mintlify.com/docs/api-playground/openapi-setup). [All Mintlify recipes](https://agentreadychecklist.com/platforms/mintlify/#ar-act-02) ### GitBookworkaround GitBook renders API blocks from your spec but does not document serving the raw file. Host openapi.json on your API or main domain and link it from a docs page and from llms.txt. Hosted SaaS, docs read 2026-11-04. Read 2026-11-04. [gitbook.com/docs/create-content/openapi](https://gitbook.com/docs/create-content/openapi). [All GitBook recipes](https://agentreadychecklist.com/platforms/gitbook/#ar-act-02) ### ReadMerecipe Upload openapi.json (rdme CLI or GitHub Action) and turn on API Catalog so /.well-known/api-catalog links each spec. Hosted SaaS, docs read 2026-11-04. Read 2026-11-04. [docs.readme.com/main/docs/openapi](https://docs.readme.com/main/docs/openapi). [All ReadMe recipes](https://agentreadychecklist.com/platforms/readme/#ar-act-02) ### Salesforce B2C Commerce (SFRA and PWA Kit / Composable Storefront)workaround Storefronts have no OpenAPI file by default; if you expose an API, serve openapi.json through ssr.js and link it. Hosted SaaS (B2C Commerce help release 264.0.0); PWA Kit retail-react-app 10.3.0 and pwa-kit-runtime 3.21.0 on npm, read 2026-11-04. Read 2026-11-04. [developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-sitemap.html](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-sitemap.html). [All Salesforce B2C Commerce (SFRA and PWA Kit / Composable Storefront) recipes](https://agentreadychecklist.com/platforms/salesforce-commerce-cloud/#ar-act-02) ### Adobe Commerce and Magento Open Sourceworkaround Export the schema with GET /rest/default/schema?services=all (admin token) and publish the result as a static openapi.json; /swagger works only in Developer mode. 2.4.9 (GitHub tag published 2026-05-12; 2.4.10-alpha1 tagged 2026-10-13); release notes read 2026-11-04. Read 2026-11-04. [developer.adobe.com/commerce/webapi/rest/quick-reference/generate-local/](https://developer.adobe.com/commerce/webapi/rest/quick-reference/generate-local/). [All Adobe Commerce and Magento Open Source recipes](https://agentreadychecklist.com/platforms/adobe-commerce/#ar-act-02) ## What it does not do - An OpenAPI file does not make the API callable without auth an agent can finish. - Not a rule to name the file openapi.json; it must be linked. ## Common mistakes - Spec only rendered in a JavaScript viewer with no raw file link. - Spec out of date with the live API. ## Related - Guide: [How to publish an OpenAPI file agents can find](https://agentreadychecklist.com/guides/publish-openapi-agents-can-find/) - Term: [OpenAPI](https://agentreadychecklist.com/glossary/openapi/) ## Sources - [github.com/agentready-org/standard/blob/main/spec/spec.md](https://github.com/agentready-org/standard/blob/main/spec/spec.md)read 2026-11-04 - [rfc-editor.org/rfc/rfc9727](https://www.rfc-editor.org/rfc/rfc9727)read 2026-11-04 - [nextjs.org/docs/app/api-reference/file-conventions/public-folder](https://nextjs.org/docs/app/api-reference/file-conventions/public-folder)read 2026-11-04 - [docs.astro.build/en/basics/project-structure/](https://docs.astro.build/en/basics/project-structure/)read 2026-11-04 - [nuxt.com/docs/guide/directory-structure/public](https://nuxt.com/docs/guide/directory-structure/public)read 2026-11-04 - [svelte.dev/docs/kit/project-structure](https://svelte.dev/docs/kit/project-structure)read 2026-11-04 - [reactrouter.com/how-to/resource-routes](https://reactrouter.com/how-to/resource-routes)read 2026-11-04 - [docs.netlify.com/manage/routing/headers/](https://docs.netlify.com/manage/routing/headers/)read 2026-11-04 - [developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/)read 2026-11-04 - [shopify.dev/docs/apps/build/online-store/app-proxies](https://shopify.dev/docs/apps/build/online-store/app-proxies)read 2026-11-04 - [help.webflow.com/hc/en-us/articles/40846212086035-Webflow-Cloud-overview](https://help.webflow.com/hc/en-us/articles/40846212086035-Webflow-Cloud-overview)read 2026-11-04 - [framer.com/help/articles/static-files/](https://www.framer.com/help/articles/static-files/)read 2026-11-04 - [support.wix.com/en/article/understanding-your-sites-llms-txt-file](https://support.wix.com/en/article/understanding-your-sites-llms-txt-file)read 2026-11-04 - [support.squarespace.com/hc/en-us/articles/47434125611277-Create-an-llms-txt-file (the article needs a Squarespace sign-in to read)](https://support.squarespace.com/hc/en-us/articles/47434125611277-Create-an-llms-txt-file)read 2026-11-04 - [developers.hubspot.com/docs/cms/start-building/features/storage/file-manager](https://developers.hubspot.com/docs/cms/start-building/features/storage/file-manager)read 2026-11-04 - [docusaurus.io/docs/static-assets](https://docusaurus.io/docs/static-assets)read 2026-11-04 - [mintlify.com/docs/api-playground/openapi-setup](https://mintlify.com/docs/api-playground/openapi-setup)read 2026-11-04 - [gitbook.com/docs/create-content/openapi](https://gitbook.com/docs/create-content/openapi)read 2026-11-04 - [docs.readme.com/main/docs/openapi](https://docs.readme.com/main/docs/openapi)read 2026-11-04 - [developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-sitemap.html](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-sitemap.html)read 2026-11-04 - [developer.adobe.com/commerce/webapi/rest/quick-reference/generate-local/](https://developer.adobe.com/commerce/webapi/rest/quick-reference/generate-local/)read 2026-11-04 - [ora.ai/api/checks, contract 1.38.0](https://ora.ai/api/checks?utm_source=agentreadychecklist.com&utm_medium=referral&utm_campaign=requirement)read 2026-11-05 - [ora.ai/llms-full.txt](https://ora.ai/llms-full.txt?utm_source=agentreadychecklist.com&utm_medium=referral&utm_campaign=requirement)read 2026-11-05 - [registry.npmjs.org/ax, the ax README](https://registry.npmjs.org/ax)read 2026-11-05 Verify with Ora The scanner this site recommends for the whole checklist. 132 checks, a score out of 100, no account. `npx ax@0.10 audit --min-score ` [Why Ora, and its limits](https://agentreadychecklist.com/verify-with-ora/) Fix it on - [Next.js (App Router)recipe](#p-nextjs-app-router) - [Astrorecipe](#p-astro) - [Nuxtrecipe](#p-nuxt) - [SvelteKitrecipe](#p-sveltekit) - [Remix and React Router (framework mode)recipe](#p-remix-react-router) - [Plain static hosting (Netlify, Vercel static, Cloudflare Pages, GitHub Pages, S3 and CloudFront)recipe](#p-static-hosting) - [WordPress and Elementorrecipe](#p-wordpress-elementor) - [Shopify (Online Store 2.0 themes)workaround](#p-shopify) - [Webflowworkaround](#p-webflow) - [Framerrecipe](#p-framer) - [Wix (Wix Editor and Wix Studio)workaround](#p-wix) - [Squarespace (version 7.1)workaround](#p-squarespace) - [HubSpot CMS (Content Hub)workaround](#p-hubspot-cms) - [Docusaurusrecipe](#p-docusaurus) - [Mintlifyrecipe](#p-mintlify) - [GitBookworkaround](#p-gitbook) - [ReadMerecipe](#p-readme) - [Salesforce B2C Commerce (SFRA and PWA Kit / Composable Storefront)workaround](#p-salesforce-commerce-cloud) - [Adobe Commerce and Magento Open Sourceworkaround](#p-adobe-commerce) Last reviewed 2026-11-05. AgentReady v2.0, read 2026-11-04.