Skip to content
Methodology

API Catalog (RFC 9727)

ia.api-catalog · 4.10

Act SHOULD Recommendation AR-READ-06 AR-ACT-02

Why it matters

An API Catalog (RFC 9727 with an RFC 9264 linkset) gives agents one discovery endpoint for all APIs of the site. It links to OpenAPI documents, human docs and health endpoints.

How to fix it

Serve /.well-known/api-catalog as an application/linkset+json document.

  1. Create a linkset with one entry per API and service-desc, service-doc and status links.

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

  2. Serve it at /.well-known/api-catalog with Content-Type application/linkset+json.

Verify

curl -sf https://{domain}/.well-known/api-catalog | jq -e '.linkset | length > 0'

Expected: exit code 0

Run a new scan for this checkpoint:

isagentready results {domain} --checkpoint ia.api-catalog
Details Mapping, lifecycle and references
AR mapping
Full match
Score role
Bonus
Introduced
2026-08-24
Methodology version
2026-10-22

Checkpoint data (JSON)