# API catalog

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

**[Capabilities](/docs/capabilities)** · checked once per host (item type `api_catalog`) · 6 checks that can fail it

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** (L2)

Several independent organisations run it in production, though it is still niche on the open web. Direction of travel: ▲ rising, as of 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](https://vercel.com/.well-known/api-catalog) |
| Supabase | production | [supabase.com](https://supabase.com/.well-known/api-catalog) |
| Hugging Face | production | [huggingface.co](https://huggingface.co/.well-known/api-catalog) |
| Cloudflare (developer docs) | production | [developers.cloudflare.com](https://developers.cloudflare.com/.well-known/api-catalog) |

## 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.

| Check | Kind | Raises | On whose authority |
|---|---|---|---|
| API Catalog Malformed Linkset | high severity | conformance, usability | specification: [Linkset: Media Types and a Link Relation Type for Link Sets](https://www.rfc-editor.org/rfc/rfc9264.html) |
| API Catalog No API Links | high severity | conformance, usability | specification: [api-catalog: A Well-Known URI and Link Relation to Help Discover APIs](https://www.rfc-editor.org/rfc/rfc9727.html) |
| apiCatalog HTTPS Downgrade | medium severity | usability, security ([CWE-319](https://cwe.mitre.org/data/definitions/319.html)) | Lumar readiness bar<br>Related: [OWASP API API8 (2023) — Security Misconfiguration](https://api-security.owasp.org/editions/2023/en/0xa8-security-misconfiguration/); [ASVS V12.2.1 (5.0.0) — TLS for external HTTP services](https://github.com/OWASP/ASVS/blob/v5.0.0/5.0/docs_en/OWASP_Application_Security_Verification_Standard_5.0.0_en.json) |
| API Catalog Wrong Media Type | medium severity | conformance, usability | specification: [api-catalog: A Well-Known URI and Link Relation to Help Discover APIs](https://www.rfc-editor.org/rfc/rfc9727.html) |
| API Catalog Insecure Link | medium severity | usability, security ([CWE-319](https://cwe.mitre.org/data/definitions/319.html)) | Lumar readiness bar, beyond [api-catalog: A Well-Known URI and Link Relation to Help Discover APIs](https://www.rfc-editor.org/rfc/rfc9727.html)<br>Related: [OWASP API API8 (2023) — Security Misconfiguration](https://api-security.owasp.org/editions/2023/en/0xa8-security-misconfiguration/); [ASVS V12.2.1 (5.0.0) — TLS for external HTTP services](https://github.com/OWASP/ASVS/blob/v5.0.0/5.0/docs_en/OWASP_Application_Security_Verification_Standard_5.0.0_en.json) |
| API Catalog Internal Link | medium severity | usability, security ([CWE-200](https://cwe.mitre.org/data/definitions/200.html)) | specification: [api-catalog: A Well-Known URI and Link Relation to Help Discover APIs](https://www.rfc-editor.org/rfc/rfc9727.html)<br>Related: [OWASP API API8 (2023) — Security Misconfiguration](https://api-security.owasp.org/editions/2023/en/0xa8-security-misconfiguration/) |
| API Catalog Missing Profile | informational | nothing | specification: [api-catalog: A Well-Known URI and Link Relation to Help Discover APIs](https://www.rfc-editor.org/rfc/rfc9727.html) |

## Examples

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

**Correct**

```json
{
  "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 wrong**

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc9727.html) | Published RFC, June 2025 | specification |
| [RFC 9264 — Linkset: Media Types and a Link Relation Type for Link Sets](https://www.rfc-editor.org/rfc/rfc9264.html) | Published RFC, July 2022 | specification |

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