OpenAPI / API Discoverability
stableCategory: ai-signals · Methodology v4.5
Can an AI agent find a machine-readable description of your API?
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
What this parameter measures
Can an AI agent find a machine-readable description of your API? That is what this parameter checks. friendly4AI scans for 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 your homepage <head> that point to an OpenAPI or GraphQL spec, and inline mentions of openapi, swagger.json, or graphql in the page HTML. Any one of these is enough to count as a discoverable spec.
Why it matters 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. When an OpenAPI or GraphQL document is discoverable, AI tools can understand your endpoints, parameters, and response shapes, then invoke them on a user's behalf instead of guessing from HTML. Discoverability is also the gate for the rest of this category: friendly4AI uses this parameter as the API-detection trigger, so a discoverable spec is what activates the other API-conditional checks below.
How we score it
This is a binary AI-Specific Signals parameter, and the scanner matches the published rubric exactly: it passes (100) when at least one valid spec is discoverable through any channel, and fails (0) when none is found. There is no partial tier. This parameter is also 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, so the weighted contribution of this parameter and the other API-conditional checks counts. When no API is detected, the API-conditional parameters carry an effective weight of zero and are excluded from the score rather than penalizing you.
How to fix common issues
- Publish an OpenAPI 3.x specification at a standard path such as
/openapi.jsonor/api/docsso the scanner can prefetch it. - Add a
<link rel="openapi" href="/openapi.json">(or a GraphQL equivalent) in your homepage<head>to give agents a second discovery path. - Reference your spec by name in visible docs — even an inline
openapiorswagger.jsonmention is detected. - If you have no API yet, consider adding even a simple search endpoint with a spec — it activates this whole category for your site.
- Re-scan after publishing to confirm the spec is discovered and the API group is active.
Version History
- Introduced
- v1
- Last changed
- v4.4
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…