API Catalog at /.well-known: how agents find your APIs

What it is

/.well-known/api-catalog (RFC 9727) is a document at a predictable address that links to your API descriptions (OpenAPI, AsyncAPI, etc.). The format is a linkset (RFC 9264): a set of links with rel types. It’s a “table of contents” of your programmatic interfaces for machines.

Why it matters for AI agents

An agent that needs to call your API rather than read a page must first find it. Without a catalog it guesses URLs or parses HTML docs. api-catalog gives a direct machine-readable pointer: here’s the API description, here are its endpoints — the agent immediately knows how to integrate with you.

Minimal working example

GET /.well-known/api-catalog HTTP/1.1

{
  "linkset": [
    {
      "anchor": "https://example.com",
      "service-desc": [
        { "href": "https://example.com/openapi.json", "type": "application/openapi+json" }
      ]
    }
  ]
}

Content-Type: application/linkset+json. The rel types (service-desc, service-doc) point to the API description and documentation.

Right vs wrong

Right	Wrong
Served at /.well-known/api-catalog	An arbitrary path
application/linkset+json, a valid linkset	Plain text/HTML instead of a linkset
Absolute href, standard rels	Relative links / made-up rels
Links to real, reachable API descriptions	Broken links to a non-existent OpenAPI

Common mistakes

• Wrong Content-Type — not application/linkset+json.
• Broken links to API descriptions (404 on the OpenAPI).
• Relative href instead of absolute.
• A catalog that exists but isn’t advertised via a Link header with rel="api-catalog" (see the Link headers guide).

How to verify

A scan checks for the catalog and its format. Manually:

curl -s https://example.com/.well-known/api-catalog | jq .
curl -sI https://example.com/.well-known/api-catalog | grep -i content-type

Expect a valid linkset and application/linkset+json.