Public API surface: what the check tests and how to fix it

Weight 2. Passes on a JSON or YAML answer from /api/ or api.<domain>, or 3+ API links on the homepage. No API means fail, and the other API checks skip.

Agent Auth · Weight 2 in the w2agent Score

How common is it?

23% 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

The audit makes two unauthenticated GET requests: <your origin>/api/ and https://api.<domain>/, where the domain is the last two labels of your hostname (so example.co.uk is probed as api.co.uk). Each has a 5-second limit and one retry after 2 seconds on a 5xx or network error.

  • Pass 100: either response has a 2xx or 4xx status and a content type containing json or yaml. The 4xx case is deliberate: an API that rejects an anonymous call with a JSON error still proves it exists.
  • Otherwise the audit counts links on the homepage only. A link counts when its href contains /api followed by / or a closing quote, or contains api. plus the exact hostname that was audited. Three or more links pass, one or two give partial 50.
  • Fail 0: none of the above. This check is never skipped.

Because www.example.com is audited as a www host, a homepage link to api.example.com does not count as an API link, although the probe in step one still reaches that host. A link to /api-docs does not count either, because /api must be followed by / or a quote.

Why it matters to agents

This is the entry point for the rest of Agent Auth. When it fails, the audit skips the OpenAPI, developer portal, agent auth docs, scoped permissions and API catalog checks, and skips OAuth discovery unless the audit also found an MCP endpoint. A skipped check is not counted against you. A pass or partial on one of them is kept even if this one failed.

If you run a content site with no API, a fail here is the correct reading, not a defect. As of rubric 3.1 the Agent Auth category carries 0.2 of the overall score, and with the other checks skipped this check is usually the one scored check left in it, so a no-API site typically gets 0 for the category. It is not guaranteed: a root protected resource metadata file keeps OAuth discovery scoring, and a pass or partial on developer portal (for example on a docs. host) also survives the skip. Do not invent an API to change that. The check cannot tell "no API wanted" from "API not exposed".

Nothing in the standards says what a "public API" is. This check is a heuristic for whether an agent could find something to call.

How to fix it

Only if you have an API that outsiders may call:

  • Answer on a predictable path. Return JSON, even for anonymous callers: a 401 with a JSON body counts, a bare HTML login page does not. Add a WWW-Authenticate header (RFC 9110, section 11.6.1) so a client knows how to authenticate; the audit does not require it here.
  • Serve the API root at https://example.com/api/ or https://api.example.com/, or both, with Content-Type: application/json.
  • Describe it so agents can use it: an OpenAPI document, listed in an API catalog, per RFC 9727.
  • Link to the API from the homepage with paths like /api/v1/. Three links reach pass without a live endpoint, but they are weaker evidence than a real answer.

Check it with curl -i https://example.com/api/ and confirm the status and Content-Type header.

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 →