---
title: "Publish OpenAPI that agents find | Agent Ready Checklist"
description: "How to publish an OpenAPI file agents can find. Serve the raw contract, link it from docs and the home page, and list it in /.well-known/api-catalog."
canonical: https://agentreadychecklist.com/guides/publish-openapi-agents-can-find
site: "Agent Ready Checklist"
last_updated: 2026-11-05
date: 2026-11-04
section: "Guides"
---

# Publish OpenAPI that agents find | Agent Ready Checklist

> How to publish an OpenAPI file agents can find. Serve the raw contract, link it from docs and the home page, and list it in /.well-known/api-catalog.

Source: https://agentreadychecklist.com/guides/publish-openapi-agents-can-find
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).

# How to publish an OpenAPI file agents can find

Serve the raw contract, link it from docs and the home page, and list it in /.well-known/api-catalog. It covers 2 requirements: AR-ACT-02, AR-READ-06. RFC 9727 defines /.well-known/api-catalog as an application/linkset+json document. On the seven study sites that shipped openapi.json, agents fetched it in 112 of 541 runs (21%).

## Before you start

You need the OpenAPI document your API already has, or the means to generate one from the code.

## Steps

1.  **[AR-ACT-02: OpenAPI contract.](https://agentreadychecklist.com/checklist/ar-act-02/)** Describe the public API with a machine-readable OpenAPI contract.
    
    ```bash
    curl -fsSL https://agentreadychecklist.com/kit/verify.sh | bash -s -- https://example.com --only=openapi
    ```
    
     Watch for: Spec only rendered in a JavaScript viewer with no raw file link.
2.  **[AR-READ-06: Link the discovery files.](https://agentreadychecklist.com/checklist/ar-read-06/)** Link discovery files (llms.txt, .well-known/\*, openapi.json) from content agents already visit: the footer, <link rel="alternate"> in the head, or a resources section.
    
    ```bash
    curl -fsSL https://agentreadychecklist.com/kit/verify.sh | bash -s -- https://example.com --only=llms-linked,openapi
    ```
    
    Watch for: llms.txt published at the root with nothing pointing to it.
3.  **List it in the API catalog.** RFC 9727 defines /.well-known/api-catalog as a linkset. Point a service-desc relation at the OpenAPI file.
    
    ```json
    {"linkset":[{"anchor":"https://example.com/api","service-desc":[{"href":"https://example.com/openapi.json","type":"application/vnd.oai.openapi+json"}]}]}
    ```
    

## How you know it is done

You are done when the raw document is served as JSON or YAML, the home page and docs link to it, and the kit openapi check prints PASS with the path it found.

## The facts behind it

-   On the seven study sites that shipped openapi.json, agents fetched it in 112 of 541 runs (21%).primary source, 2026-08-28: [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 2026-11-04
-   97% of 122 openapi.json fetches arrived through a link rather than a guessed path.primary source, 2026-08-28: [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents), read 2026-11-04
-   RFC 9727 defines /.well-known/api-catalog as an application/linkset+json document.primary source: [rfc-editor.org/rfc/rfc9727](https://www.rfc-editor.org/rfc/rfc9727), read 2026-11-04
-   Cloudflare checks for Link response headers using the api-catalog, service-desc, service-doc and describedby relations.primary source: [isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md](https://isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md), read 2026-11-04
-   The spec lists operation IDs, typed responses and errors, /v1/ versioning and documented rate limits as OpenAPI 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

## Sources

-   [vercel.com/kb/guide/make-your-site-readable-by-ai-agents](https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents)read 2026-11-04
-   [rfc-editor.org/rfc/rfc9727](https://www.rfc-editor.org/rfc/rfc9727)read 2026-11-04
-   [isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md](https://isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md)read 2026-11-04
-   [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

Edition

Data

2026-11-04

Reviewed

2026-11-05

Spec

AgentReady v2.0, 273d2d7

Crawl

13,071 rows, 2026-11-04

Ora

132 checks, contract 1.38.0, 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 <url> --min-score <n>`

[Why Ora, and its limits](https://agentreadychecklist.com/verify-with-ora/)

Method

-   [How rows, commands and rates are made](https://agentreadychecklist.com/method/)
-   [How an Ora check is matched to a row](https://agentreadychecklist.com/checklist/ora-checks/)
-   [Pass rates by rank band](https://agentreadychecklist.com/data/by-rank/)

Sources and read dates sit at the foot of the page.

Last reviewed 2026-11-05. AgentReady v2.0, read 2026-11-04.