API catalog

What the scanner requests

• /.well-known/api-catalog
• /api-catalog.json
• /.well-known/ai-plugin.json

What is measured

The scanner GETs /.well-known/api-catalog with Accept: application/linkset+json, falling back to /api-catalog.json and the legacy /.well-known/ai-plugin.json, and parses the response as a linkset (RFC 9264). It passes when the linkset array holds at least one entry with an anchor and a service-desc link pointing at an API description, as defined by RFC 9727, and at least one same-origin service-desc or service-doc target that the scan actually requested and that answered 2xx - the anchor and the href are a declaration, and only an observed response identifies a callable API. It partially passes when a linkset is served but its entries carry only service-doc, service-meta or status links, or have no anchor, and also when every service-desc or service-doc target it names is off-origin, outside the probe set or answering an error, so no target was observed to answer.

Reproduce it yourself

You do not have to take our word for any of this. Run the same measurement against your own domain:

              DOMAIN=https://your-domain.example
curl -sS -H 'Accept: application/linkset+json' "$DOMAIN/.well-known/api-catalog" | jq '.linkset[] | {anchor, "service-desc": .["service-desc"], status: .status}'
            

The fix

This is the artifact to ship. It is the complete change, not a description of one.

              {
  "linkset": [
    {
      "anchor": "https://your-domain.example/apis/public_api",
      "service-desc": [
        { "href": "https://your-domain.example/openapi.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://your-domain.example/docs/", "type": "text/html" }
      ],
      "status": [
        { "href": "https://your-domain.example/status.json", "type": "application/json" }
      ]
    }
  ]
}
            

Standards referenced

• RFC 9727

Related checks