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/andhttps://example.com/developersboth 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_documentationto 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.