OpenAPI / API Discoverability
stableCategory: ai-signals · Methodology v4.5
It measures one thing: can a machine reach at least one of your API specs without a human reading the page?
Signal Source
- Source
https://{domain}/ (homepage HTML, headers, prefetched well-known + OpenAPI paths)- Kind
- http_response
Score Bands
| Verdict | Condition |
|---|---|
| Pass | At least one valid machine-readable API spec is discoverable — a prefetched OpenAPI/Swagger document at a standard path, a <link> to an OpenAPI/GraphQL spec, or an inline openapi/swagger/graphql mention in the homepage HTML |
| Partial | Not applicable — this is a binary parameter with no middle tier |
| Fail | No machine-readable API spec is discovered in the homepage HTML, headers, or prefetched well-known paths |
Description
API discoverability checks whether an AI agent can find a machine-readable description of your API — an OpenAPI, Swagger, or GraphQL specification — from your homepage HTML, HTTP headers, or standard well-known paths. friendly4AI scores it as a binary signal: pass (100) if at least one valid spec is discoverable, fail (0) if none is.
What does API discoverability measure?
It measures one thing: can a machine reach at least one of your API specs without a human reading the page? friendly4AI checks three channels for that spec.
- Prefetched spec documents at standard paths —
/openapi.json,/openapi.yaml,/v3/api-docs,/swagger.json,/.well-known/openapi,/api/openapi.json, and similar. <link>tags in the homepage<head>that point to an OpenAPI or GraphQL spec.- Inline mentions of
openapi,swagger.json, orgraphqlin the page HTML.
A hit on any single channel counts as a discoverable spec.
Why does it matter for AI-readiness?
A rendered web page tells a human what you do. A machine-readable API spec tells an autonomous agent how to call you. Once an OpenAPI or GraphQL document is discoverable, AI tools can read your endpoints, parameters, and response shapes, then call them on a user's behalf rather than guessing from the HTML.
This parameter also gates the rest of the category. friendly4AI treats it as the API-detection trigger, so finding a spec is what switches on the other API-conditional checks: API schema quality for agents, action API, and AI manifests coverage.
How is it scored?
This is a binary AI-Specific Signals parameter, and the scanner follows the published rubric exactly:
- Pass (100) — at least one valid spec is discoverable through any channel.
- Fail (0) — none is found. There is no partial tier.
The parameter doubles as the activation switch for friendly4AI's API-conditional group. When it passes — or when its evidence carries an /openapi.json-style spec path — the conditional scoring evaluator marks the api group active, and the weighted contribution of this parameter and the other API-conditional checks counts toward your score. When no API is detected, those parameters carry an effective weight of zero and drop out of the score entirely, so a missing API never costs you points.
How do you fix it?
- Publish an OpenAPI 3.x specification at a standard path such as
/openapi.jsonor/api/docs, where the scanner can prefetch it. - Add a
<link rel="openapi" href="/openapi.json">(or a GraphQL equivalent) to your homepage<head>. That gives agents a second way in. - Name your spec in visible docs. Even an inline
openapiorswagger.jsonmention is detected. - No API yet? A single search endpoint with a spec is enough to activate this whole category for your site.
- Re-scan after publishing to confirm the spec is found and the API group is active.
Version History
- Introduced
- v1
- Last changed
- v4.5
Key takeaways
- Signal: https://{domain}/ (homepage HTML, headers, prefetched well-known + OpenAPI paths)
- Category: AI-Specific Signals
- Passes when: At least one valid machine-readable API spec is discoverable — a prefetched O…