API catalog — agent readiness

An index at /.well-known/api-catalog listing the site's APIs and their descriptions.

Why an agent cares

One address tells an agent every API the site offers and where each one is described, instead of guessing paths like /openapi.json. It is an IETF standard, so a catalog in the wrong format or pointing at nothing breaks a rule rather than a preference.

Adoption

Early production. Several independent organisations run it in production, though it is still niche on the open web.

Direction of travel: ▲ rising, as at 2026-10-03.

Moved from 4 real catalogs in a 74-site census (May 2026) to 7 among 37 well-known agent-focused sites (October 2026), and Cloudflare's Agent Readiness score now checks for one.

Adopter	Depth	Evidence
Vercel	`production`	vercel.com
Supabase	`production`	supabase.com
Hugging Face	`production`	huggingface.co
Cloudflare (developer docs)	`production`	developers.cloudflare.com

What we check

Absence is never a finding. Every check below runs only when this technology is detected, so a site that has not adopted this is not assessed on it and appears in no report. 6 of these 7 can fail it. In Lumar these appear once per site, in the site-wide results of each crawl.

Check	Severity	Raises	On whose authority
API Catalog Malformed Linkset	high	conformance, usability	specification: Linkset: Media Types and a Link Relation Type for Link Sets
Supporting documents: Linkset: Media Types and a Link Relation Type for Link Sets Required by Linkset: Media Types and a Link Relation Type for Link Sets. Bad: the document breaks the linkset JSON structure (RFC 9264): "linkset" isn't its only member or isn't an array, a relation isn't a list of objects, or a link has no "href", so a parser rejects or misreads it. Fix: shape it as {"linkset": [{"anchor": "...", "item": [{"href": "https://api.example.com/"}]}]}.
API Catalog No API Links	high	conformance, usability	specification: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs
Supporting documents: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs Required by api-catalog: A Well-Known URI and Link Relation to Help Discover APIs. Bad: the catalog holds no links at all, but RFC 9727 requires it to link to the site's API endpoints, so an agent finds nothing to call. Fix: add an "item" link for each API, e.g. "item": [{"href": "https://api.example.com/v1"}].
apiCatalog HTTPS Downgrade	medium	usability, security (CWE-319)	Lumar readiness bar
An advertised HTTP destination permits unencrypted communication. OWASP API API8 (2023) — Security Misconfiguration ASVS V12.2.1 (5.0.0) — TLS for external HTTP services Only advertised transport configuration is observed; API deployment security is not fully assessed. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
API Catalog Wrong Media Type	medium	conformance, usability	specification: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs
Supporting documents: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs Required by api-catalog: A Well-Known URI and Link Relation to Help Discover APIs. Bad: the catalog isn't served as application/linkset+json, the one format RFC 9727 requires, so a client asking for a linkset may not parse it. Fix: serve it as application/linkset+json, with the RFC 9727 profile parameter (see API Catalog Missing Profile).
API Catalog Insecure Link	medium	usability, security (CWE-319)	Lumar readiness bar, beyond api-catalog: A Well-Known URI and Link Relation to Help Discover APIs
Supporting documents: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs Lumar readiness bar: no specification requires this. Provisional security check; precision has not yet been measured. Bad: the catalog lists an API on plain http://, so an agent that follows it sends its requests unencrypted, along with any credential the API asks for. A Lumar bar: RFC 9727 only asks for the catalog itself over TLS. Fix: serve the API over https and link "href": "https://api.example.com/". An advertised HTTP destination permits unencrypted communication. OWASP API API8 (2023) — Security Misconfiguration ASVS V12.2.1 (5.0.0) — TLS for external HTTP services Only advertised transport configuration is observed; API deployment security is not fully assessed. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
API Catalog Internal Link	medium	usability, security (CWE-200)	specification: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs
Supporting documents: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs Related guidance in api-catalog: A Well-Known URI and Link Relation to Help Discover APIs. Provisional security check; precision has not yet been measured. Bad: the catalog lists an API on localhost, a private IP or an internal name, publishing internal metadata to anyone who reads it, which RFC 9727 tells publishers to audit out. Fix: remove internal APIs from the public catalog. Public discovery metadata reveals internal service addresses. OWASP API API8 (2023) — Security Misconfiguration Reachability, authorization and SSRF exploitation are not tested. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
API Catalog Missing Profile	informational	nothing	specification: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs
Supporting documents: api-catalog: A Well-Known URI and Link Relation to Help Discover APIs api-catalog: A Well-Known URI and Link Relation to Help Discover APIs permits this, so it never fails the site. Informational (does not fail API Catalog Valid): the Content-Type carries no profile parameter naming RFC 9727, which the RFC recommends so a client can tell an API catalog from any other linkset. Consider adding profile="https://www.rfc-editor.org/info/rfc9727".

Examples

Both run through the same checks as a live scan: the first passes, the second is flagged.

correctjson

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

present but wrongjson

{
  "version": 1,
  "linkset": [
    {
      "anchor": "https://example.com/.well-known/api-catalog",
      "item": { "href": "https://api.example.com/v1" }
    }
  ]
}

Specifications

Document	Revision	Kind
RFC 9727 — api-catalog: A Well-Known URI and Link Relation to Help Discover APIs	Published RFC, June 2025	specification
RFC 9264 — Linkset: Media Types and a Link Relation Type for Link Sets	Published RFC, July 2022	specification

Last re-read against the published documents: 2026-10-05.