Discoverable API endpoints: what the check tests and how to fix it

Weight 1. Passes if a crawled page links to openapi, swagger, api-docs or graphql, labels a link 'API reference', or has link rel=api. Nothing is fetched.

Agent Protocols · Weight 1 in the w2agent Score

How common is it?

26% of 1223 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

This check reads the HTML the audit already fetched, which is the homepage plus up to nine more pages chosen from your sitemap and homepage links. It makes no new requests and never opens a link it finds. It collects an indicator for each of these:

  • An <a href> whose address contains openapi, swagger, api-docs or graphql. The match is a case-sensitive substring on the href as written, so /docs/graphql-intro counts and /Swagger does not.
  • An <a> whose visible text matches "REST API" or "GraphQL API", or "API" followed by reference, doc, docs, documentation or explorer, in any case. "API reference" counts; "Developers" does not.
  • A <link rel="api"> element in the head.

One or more indicators gives pass, 100. None gives fail, 0. There is no partial. The message reports how many indicators it found.

Three things it does not do:

  • It does not request the target. A dead /openapi.json link passes.
  • It does not read <link rel="service-desc">, <link rel="service-doc"> or <link rel="api-catalog"> elements, or an HTTP Link header. Only <a> links are scanned for the strings above.
  • It does not look at /.well-known/api-catalog or probe /api/. That is the job of public API surface, OpenAPI document and API catalog, which are separate checks.

Why it matters to agents

An agent or a developer who lands on your pages can only follow what is linked. A visible link to machine-readable API documentation is the cheapest signal that you have an API at all. The OpenAPI specification describes HTTP APIs in a document that tools can read, and the GraphQL specification defines introspection so a client can ask a server for its schema. Neither specification says anything about homepage links, so this check is a heuristic, not a standards test.

The rel="api" value is not in the IANA link relations registry as fetched on the verification date. The registered relations for this job are service-desc and service-doc (RFC 8631) and api-catalog (RFC 9727). The check still counts rel="api", but a registered relation by itself earns nothing here.

If you have no public API, a fail is accurate. Do not add links to documentation that does not exist.

How to fix it

Only if you offer an API to outsiders:

  1. Link to your API documentation from the homepage or a page in your sitemap, using plain <a> tags. A path such as /docs/api-docs or /openapi.json, or link text such as "API reference", is enough for this check.
  2. Publish the machine-readable description at that address: an OpenAPI document, or a GraphQL endpoint with introspection enabled if you allow it.
  3. Add the registered relations as well, for tools that look for them:
<link rel="service-desc" type="application/openapi+json" href="/openapi.json">
<link rel="service-doc" href="/docs/api">
  1. Check the links resolve, because this check will not.

For an API catalog that clients can find from your domain alone, see API catalog (RFC 9727); for the portal page itself, developer portal.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →