API Catalog SEO: How AI Agents Discover Your Public APIs

An API product can be perfectly documented and still be hard to discover.

The docs may live on a separate domain. The OpenAPI description may be buried in a repository. Authentication rules may sit on a pricing page, while a useful endpoint is only mentioned inside a tutorial.

For people, that is inconvenient. For an AI agent trying to decide whether a site has a real capability it can use, it creates ambiguity.

That is the problem an API catalog can solve. It is not an AI-search ranking trick. It is a machine-readable directory for publishers that actually expose public APIs.

This is the practical follow-up to Link Headers for AI Agents. It also fits beside MCP Server Card for Product Websites and the wider Agent SEO audit.

What An API Catalog Is

RFC 9727 defines an api-catalog link relation and the discoverable /.well-known/api-catalog location.

The catalog is a Linkset document. Its job is to list a publisher’s APIs in a predictable place, so a client can discover the API surface before it has to guess URLs or scrape documentation.

An API catalog is not the same thing as:

Resource	What it does	What it does not replace
API catalog	Lists available APIs and links to their related resources	Endpoint documentation or access control
OpenAPI description	Describes operations, parameters, responses, and servers	A top-level directory of all published APIs
Developer portal	Helps humans evaluate and learn an API	A machine-readable discovery point
MCP server card	Helps agents understand an MCP server’s capabilities and boundaries	An HTTP API inventory
llms.txt	Offers a curated readable map of a site	API contracts, authentication rules, or endpoint metadata

For an application with real external capabilities, these assets can work together. For a normal content site, they should not be manufactured just to look “agent-ready.”

Start With A Fit Check

Use an API catalog only when the answer to these questions is yes:

• Does the organization publish one or more APIs that third parties may legitimately discover?
• Does each listed API have a stable endpoint or service URL?
• Can you point to current documentation, authentication requirements, usage policy, and version information?
• Is somebody responsible for removing deprecated entries when the API changes?

If the answer is no, pause here. Improve the existing sitemap, internal links, Technical SEO, and readable documentation instead.

An API catalog that points to a private experiment, an unmaintained endpoint, or a marketing page is worse than no catalog. It wastes discovery effort and makes an agent’s later validation harder.

The Minimum RFC 9727 Pattern

RFC 9727 requires a publisher that supports the well-known location to resolve GET /.well-known/api-catalog to an API catalog document, and to return a Link response header for HEAD requests. The catalog uses the Linkset JSON media type defined by RFC 9264.

A small catalog can look like this:

{
  "linkset": [
    {
      "anchor": "https://api.example.com/.well-known/api-catalog",
      "item": [
        {
          "href": "https://api.example.com/v1/catalog",
          "title": "Product catalog API",
          "type": "application/json"
        },
        {
          "href": "https://api.example.com/v1/audit",
          "title": "Site audit API",
          "type": "application/json"
        }
      ]
    }
  ]
}

Serve it with a Linkset content type, for example:

Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

Then expose the discovery relation from a meaningful surface such as the API host, developer portal, or relevant product domain:

Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"

The exact hosting layout can vary. The important part is that URLs resolve, the catalog describes actual APIs, and the publisher can keep it accurate.

Add Enough Context To Make The Catalog Useful

The catalog should not be a vague list of names. Before publishing, build an API inventory that a developer or agent can verify:

Field to confirm	Why it matters
Stable endpoint or API root	Lets clients distinguish a real service from a documentation page
OpenAPI URL or human documentation	Explains operations, inputs, responses, and limits
Authentication method	Prevents unsafe assumptions about anonymous access
Rate limits, pricing, and terms	Helps clients decide whether use is permitted and practical
Version and deprecation policy	Prevents agents from choosing a legacy API
Owner and review date	Makes stale entries traceable

Where appropriate, point a catalog entry to supporting documentation with a relation such as describedby, service-doc, or service-desc. Use relation values precisely; do not label every unrelated resource as an API.

This is where Auth.md and OAuth metadata and an Agent Skills Index may become relevant. They address different problems: protected-resource discovery and capability guidance. Neither is a substitute for clear API documentation.

A Four-Step Publishing Workflow

1. Confirm fit. List only APIs that are intentionally public or available to authorized third parties.
2. Inventory facts. Record the endpoint, docs, OpenAPI URL, authentication, limits, version, owner, and review date for each one.
3. Publish discovery. Serve the Linkset at /.well-known/api-catalog, include the expected content type, and add an api-catalog Link header where it helps clients find it.
4. Validate after deployment. Check status codes, headers, JSON shape, linked URLs, and whether the docs still describe the live service.

The workflow is deliberately operational. It gives your team an asset to maintain, not a one-time metadata file.

Test The Live Deployment

Start with the API host:

curl -I https://api.example.com/.well-known/api-catalog
curl https://api.example.com/.well-known/api-catalog
curl -I https://api.example.com/

Confirm all of the following:

• GET /.well-known/api-catalog resolves successfully.
• The response declares application/linkset+json and, when used, the RFC 9727 profile.
• A HEAD request returns an api-catalog Link header as required by the standard.
• Every item URL resolves to a real API rather than a dead endpoint or generic landing page.
• The associated OpenAPI, docs, auth, and terms pages match the currently deployed API.
• Deprecated APIs are either removed or clearly marked through the publisher’s versioning policy.

Use Bot Simulator and Agent SEO Audit to inspect the broader discovery surface, but do not expect an audit score to prove that the API itself is safe or usable. API behavior still needs product and security testing.

What API Catalog SEO Does And Does Not Do

API catalogs can reduce ambiguity around discovery. They may help a developer, client, crawler, or agent find the correct place to begin evaluating a public API.

They do not:

• guarantee Google indexing, rankings, AI citations, or agent adoption;
• make a private API public;
• replace OAuth, scopes, consent, rate limiting, or abuse controls;
• replace OpenAPI, developer docs, or a stable versioning policy;
• make a content-only site more useful by itself.

Google’s current guidance for generative AI features remains grounded in ordinary search quality and technical eligibility. Keep the catalog in its narrow, honest role: API discovery.

The Next Action For Fennec Users

If your product exposes a real public API, use this quick checklist:

1. Inventory the APIs you are prepared to support.
2. Confirm every API has a stable endpoint, current docs, and clear access rules.
3. Publish and validate /.well-known/api-catalog according to RFC 9727.
4. Link it from the relevant API host or developer portal with rel="api-catalog".
5. Run the public site through Agent SEO Audit and keep the rest of the site crawlable with Technical SEO.

If your site does not expose APIs, keep the simpler discovery foundations healthy instead: a sitemap, accurate internal links, useful content, and any machine-readable resources that genuinely serve readers or clients.

Sources

• IETF RFC 9727: api-catalog
• IETF RFC 9264: Linkset
• IETF RFC 8288: Web Linking
• OpenAPI Specification
• Google Search Central: Optimizing for generative AI features

Q&A

Does publishing an API catalog improve Google rankings?

No ranking benefit is guaranteed or implied. An API catalog is an API-discovery standard for publishers that have real public APIs; it does not replace crawlability, useful content, or normal SEO.

Do content-only websites need an API catalog?

Usually no. A content-only site should first maintain its sitemap, internal links, crawlability, useful pages, and any genuinely useful machine-readable resources.

Is an OpenAPI file the same as an API catalog?

No. OpenAPI describes an API. An RFC 9727 API catalog is a discoverable Linkset document that lists published APIs and can point agents or developers toward their documentation and descriptions.