Developer portal: what the check tests and how to fix it

Weight 2. Looks for an HTML page at /developers, /api and similar paths, or on docs. and developers. subdomains, with 1,000+ characters of text.

Agent Auth · Weight 2 in the w2agent Score

How common is it?

68% of 746 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 requests five paths on your origin: /developers, /developer, /api, /docs/api and /api-docs. A page counts when the response is 2xx and its content type is HTML or missing. A JSON, YAML or plain-text answer does not count here; the audit treats that as a machine endpoint, which belongs to the public API check.

If none of the five matches, it tries / on the docs., developers. and developer. subdomains of your domain (www. is dropped), one after another.

For the first page found, the audit removes scripts, styles and tags from up to 256 KB of the response, collapses whitespace and counts the characters left.

  • Pass 100: 1,000 or more characters of text.
  • Partial 50: a page was found but it is thin.
  • Fail 0: no page found. On a site that answers 200 for made-up paths (a catch-all), the five same-origin paths are not probed at all, so only the subdomains can pass.
  • Skip: no probe received any response, so the audit could not tell. Also when the public API check failed or was skipped and this one would have failed; a pass or partial is kept regardless.

The text count is taken from the HTML the server returns. A portal that renders its content with JavaScript can look thin or empty to the audit.

Why it matters to agents

No standard defines a "developer portal". This check is a heuristic: it asks whether there is a readable place that explains your API. That helps in practice because an agent that has found your API still has to learn authentication, limits and examples, and those usually live in documentation, not in the OpenAPI file.

Two standards do point at documentation. RFC 9727 says an API catalog may include links to human-readable documentation, and RFC 9728 lets protected resource metadata carry a resource_documentation URL for "information that developers might want or need to know". Neither requires a portal, and neither says that a portal page helps ranking or recommendations.

If you have no API there is nothing for a portal to document, and the check is skipped.

How to fix it

  • Serve documentation at one of the probed locations. https://docs.example.com/ and https://example.com/developers both work.
  • Put the content in the HTML response. Server-render or pre-render the documentation pages; do not rely on a script to fill an empty shell.
  • Make the landing page substantive: what the API does, how to get credentials, rate limits, and links to the OpenAPI document and to your reference. A page of under 1,000 characters scores only partial.
  • Do not redirect the path to a login wall that returns a short page.
  • If you publish protected resource metadata, set resource_documentation to this page; see OAuth discovery.

After deploying, curl -s https://example.com/developers | wc -c gives a rough size, and the Content-Type header must contain html.

What agents should read about authentication is covered by agent auth docs.

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 →