API Catalog (RFC 9727)

What is API Catalog?

API Catalog (RFC 9727) is a linkset-format JSON document at /.well-known/api-catalog that lists all public APIs on a site. It lets AI agents automatically discover available APIs without parsing documentation.

{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }]
    }
  ]
}

The Content-Type must be application/linkset+json.

Why do you need API Catalog?

AI agents operating autonomously need to find API entry points. API Catalog is the canonical place for this: an agent does a GET /.well-known/api-catalog and receives a complete list of available resources with their documentation.

A link to the API Catalog should also appear in Link headers on the home page:

Link: </.well-known/api-catalog>; rel="api-catalog"

How do you implement API Catalog?

Create a file public/.well-known/api-catalog with Content-Type: application/linkset+json. The structure per RFC 9727 is a linkset array where each element contains:

Field	Required	Description
anchor	yes	URI of the API resource
service-doc	recommended	Link to documentation (OpenAPI, Swagger)
service-desc	recommended	Link to machine-readable schema
status	no	API status (stable, deprecated)

For OAuth-protected APIs, add a link to authorization metadata:

{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }],
      "oauth-protected-resource": [{ "href": "https://api.example.com/.well-known/oauth-protected-resource" }]
    }
  ]
}

How do we check API Catalog?

The scanner performs a GET /.well-known/api-catalog with the header Accept: application/linkset+json, application/json and verifies:

1. HTTP status 200 and Content-Type of application/linkset+json or application/json
2. Valid JSON with a root linkset array
3. Non-empty linkset — at least one element with both anchor and href

Gradient scoring: 3+ valid elements → pass (1.0), 1–2 → warning (0.5), 0 → fail.