API Catalog exists (RFC 9727)

agent_protocol_api_catalog

Checks if an API Catalog exists for automated API discovery (RFC 9727).

What does this rule check?

An API Catalog at /.well-known/api-catalog provides a machine-readable index of all APIs your site exposes. It uses the linkset+json format with relations pointing to OpenAPI specs, documentation, and health endpoints.

Why is this important?

Without an API Catalog, AI agents cannot automatically discover which APIs your site offers. They must rely on documentation crawling or manual configuration, limiting automation potential.

How to fix

Create /.well-known/api-catalog returning application/linkset+json with a linkset array containing your API endpoints and their descriptions.

Examples

GET /.well-known/api-catalog

HTTP/1.1 404 Not Found

GET /.well-known/api-catalog

HTTP/1.1 200 OK
Content-Type: application/linkset+json

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

Agent fix snippet

Copy this snippet and paste it into your AI coding agent to fix this issue automatically.

Create /.well-known/api-catalog:

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