API Catalog — RFC 9727 for Agent Discovery

A single company’s domain commonly hosts several distinct APIs — a public REST API, an internal admin API, a webhooks API, maybe a GraphQL endpoint — each with its own OpenAPI spec, its own docs site, and no single place declaring that they all exist. An agent trying to understand “what can I do on this domain” has to either already know every URL, or crawl broadly and hope to stumble on the right paths.

RFC 9727 solves this with one well-known URI: /.well-known/api-catalog. A server publishes a single document there listing every API it exposes, each with links to that API’s own description document, documentation, and other metadata.

The catalog itself is formatted as a linkset (RFC 9264) — a standard structure for expressing typed relationships between resources. Each entry has an anchor (the resource being described) and typed link arrays pointing to related resources:

{
  "linkset": [
    {
      "anchor": "https://example.com/.well-known/api-catalog",
      "item": [
        { "href": "https://api.example.com/v1/health" }
      ]
    },
    {
      "anchor": "https://api.example.com/v1/health",
      "title": "Example API",
      "service-desc": [
        { "href": "https://example.com/openapi.json", "type": "application/json", "title": "Example API — OpenAPI 3.1" }
      ],
      "service-doc": [
        { "href": "https://docs.example.com", "type": "text/html", "title": "API Documentation" }
      ],
      "service-meta": [
        { "href": "https://example.com/.well-known/agent-card.json", "type": "application/json", "title": "Agent capability card" }
      ]
    }
  ]
}

The top-level entry anchors the catalog document to itself and points at each API it covers via item. Each API then gets its own entry, with service-desc (the machine-readable spec), service-doc (human documentation), and service-meta(anything else — an agent card, an MCP manifest) as separate typed link relations.

The response needs the correct media type to be a conformant linkset, not just JSON that happens to look right:

A catalog is only useful if every link in it actually works — a broken item.hrefon the catalog’s own anchor entry is the first hop any agent following the catalog takes, so it’s the most damaging place for a dead link to live. When building this for a real site, verify each URL in the finished document individually rather than assuming a path that worked for a neighboring endpoint will also work for the one you’re linking — adjacent paths on the same API can resolve very differently.

API Catalog falls under AR-CAP, the category covering capability exposure — what an agent can learn about your APIs once it has found your domain. In the live AX Audit, it’s its own named check worth up to 4 of the 100 points, scored on whether /.well-known/api-catalog exists and is a valid linkset.

ainative.ax publishes its own catalog and scores the full 4 of 4. The same pattern is live on opencapstack.com and ainative.studio as well — three independent, cross-property reference implementations of the same RFC.