OpenAPI checker

What is checked

The report opens on 4 checks of rubric v0.9. Each is described here in the rubric's own words.

OpenAPI definition

An OpenAPI document describes an HTTP API so a client can call it without guessing.

openapi is a scored check. Web standards: 70% of the score. A check in it can hold a level.

The scanner reads the OpenAPI document the site advertises and the 5 standard paths: /openapi.json, /openapi.yaml, /.well-known/openapi.json, /api/openapi.json, and /swagger.json. Advertised pointers come first: a service-desc link in the API catalog at /.well-known/api-catalog, in a Link response header, or in the homepage HTML, and homepage anchors whose URL or text names an API reference. A document found at a standard path counts as much as an advertised one. It passes when the first candidate that answers 2xx, is not HTML and parses as OpenAPI 3.x carries an openapi version string, info.title, info.version, and a non-empty paths object. It partially passes when such a document omits info.title or info.version, or when its paths object is empty. It fails when no candidate the scan requested serves an OpenAPI 3.x document, and the failure is a defect when an advertised pointer answers an error, an OpenAPI document served as HTML, or a document that is not OpenAPI 3.x. An advertised pointer that answers with a page, an HTML page, a markdown page or a copy of the homepage, is the site's catch-all: no document is served there, which is no defect. An advertised pointer the scan did not request, or that did not answer, is named and never counted as broken. It is not measured when the scan requested no candidate, or when no candidate serves a document and one answered 406, which refuses the scan's Accept header. The scan also requests a sample of the GET operations the document describes, up to a published cap, and reports what they answered; that never changes the result. It is asked only of a site where the scan saw an HTTP API.

Run the same measurement against your own site. Set the origin on the first line:

ORIGIN=https://example.com
for p in /openapi.json /.well-known/openapi.json /api/openapi.json /swagger.json; do printf '%s -> ' "$p"; curl -sSL -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: application/json, application/linkset+json;q=0.9, */*;q=0.5' "$ORIGIN$p" | jq -c '{openapi, title: .info.title, version: .info.version, paths: (.paths | length)}' 2>/dev/null || echo "no JSON OpenAPI document"; done
printf '/openapi.yaml -> '; curl -sSL -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: application/yaml, application/x-yaml;q=0.9, text/yaml;q=0.9, */*;q=0.5' "$ORIGIN/openapi.yaml" | grep -m1 -E '^(openapi|swagger):' || echo "no YAML OpenAPI document"

Read the openapi check page for its sources and the change to make.

API catalog

An API catalog lists a publisher's APIs in one document at a fixed address (RFC 9727).

api-catalog is a scored check. Web standards: 70% of the score. A check in it can hold a level.

The scanner GETs /.well-known/api-catalog, the one location RFC 9727 defines, and parses the response as a linkset (RFC 9264). It passes when the linkset array holds at least one entry with an anchor and a service-desc link pointing at an API description, as defined by RFC 9727, and at least one same-origin service-desc or service-doc target that the scan actually requested answered 2xx - the anchor and the href are a declaration, and only an observed response identifies a callable API. It partially passes when a linkset is served but its entries carry only service-doc, service-meta, or status links, or have no anchor, and also when every service-desc or service-doc target it names is off-origin, was not requested, did not answer, or answered an error, so no target was observed to answer; the detail names that cause. A service-desc target that answers with a page (HTML, markdown or a copy of the homepage) rather than JSON or an OpenAPI description, or a service-doc target that answers with a copy of the homepage, is no target that answered. With no target observed to answer, a target that answered 406, which refuses the scan's Accept header, leaves the check not measured. It fails when the path serves no linkset it can read, and the detail says what it served instead: a JSON document with no linkset entries, a linkset served as HTML, or a body that is not JSON, is served with an error, and a page (HTML, markdown or a copy of the homepage) is the site's catch-all, so no catalog is served there. It is not measured when the scan did not request /.well-known/api-catalog, or when it answered 406, which refuses the scan's Accept header. The other targets and the status relation are reported and never change the result.

Run the same measurement against your own site. Set the origin on the first line:

ORIGIN=https://example.com
curl -sSL -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: application/linkset+json, application/json;q=0.9, */*;q=0.5' "$ORIGIN/.well-known/api-catalog" | jq '.linkset[] | {anchor, "service-desc": .["service-desc"], status: .status}'

Read the api-catalog check page for its sources and the change to make.

Documentation reachable

Documentation linked as service-doc (RFC 8631), or from the homepage, is how a client learns the API.

docs is a scored check. Web standards: 70% of the score. A check in it can hold a level.

The scanner fetches the homepage and looks for public documentation it can reach without credentials: a service-doc link relation in a Link header, the HTML, or the API catalog, or an anchor whose path has a whole segment naming a documentation section, such as /docs, /developers, /reference, /guides, /dokuman, or /gelistiriciler. It requests the first homepage pointers, service-doc first, up to a published cap, and also reads the 4 standard documentation paths /docs, /documentation, /developers, and /gelistiriciler. It reads an api-catalog pointer without requesting it, so that pointer counts only when the scan requested its path for another reason. It passes when a pointer or a standard path returns 200 with readable HTML or markdown integration content. A page that is a copy of the homepage, a redirect to sign-in, or a client-side JavaScript shell is not documentation, wherever it answers. It fails when no pointer and no standard path served readable documentation, and the failure is a defect when an advertised pointer that was requested answered an error other than 406, redirected to sign-in, or served a copy of the homepage, a shell or a thin page. The detail says how many advertised pointers the scan requested. A requested pointer that gives no response is not measured and earns no partial credit. When nothing served documentation and a pointer or a standard path answered 406, which refuses the scan's Accept header, the check is not measured. It is not measured when the scan requested no pointer and no standard path. It is asked only of a site where the scan saw an HTTP API or an MCP server.

Run the same measurement against your own site. Set the origin on the first line:

ORIGIN=https://example.com
for p in /docs /documentation /developers /gelistiriciler; do curl -sSL -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7' -o /dev/null -w "%{http_code} %{content_type} %{url_effective}\n" "$ORIGIN$p"; done

Read the docs check page for its sources and the change to make.

OAuth discovery documents

OAuth metadata tells a client where and how to authorise against the API.

oauth-discovery is a scored check. Web standards: 70% of the score. A check in it can hold a level.

The scanner GETs /.well-known/oauth-authorization-server, /.well-known/openid-configuration, and /.well-known/oauth-protected-resource with no credentials. It passes when one of them returns JSON matching the format for that path: RFC 8414 or OpenID Connect metadata carrying issuer, authorization_endpoint, token_endpoint, and response_types_supported, or RFC 9728 protected resource metadata carrying resource and authorization_servers. For protected resource metadata, the scan also requests the RFC 8414 metadata of the same-origin authorization servers it names, up to a published cap. It partially passes when a document is served at a valid path but omits a member required for that format, or when every same-origin authorization server whose metadata the scan requested publishes none with issuer and token_endpoint. An authorization server on another origin, or one whose metadata was not requested or answered 406, which refuses the scan's Accept header, does not change the outcome, and the detail names it as not requested. It fails when all 3 paths answered and none serves a JSON document. It is not measured when a path the scan did not request, that did not answer, or that answered 406, which refuses the scan's Accept header, could still hold the document. It is asked only of a site where the scan saw OAuth in use: discovery metadata, a Bearer challenge, or an OAuth security scheme in its OpenAPI document.

Run the same measurement against your own site. Set the origin on the first line:

ORIGIN=https://example.com
for p in /.well-known/oauth-authorization-server /.well-known/openid-configuration /.well-known/oauth-protected-resource; do printf '%s -> ' "$p"; curl -sSL -A 'AgenticWebScore/0.3 (+https://agenticwebscore.com/bot)' -H 'Accept-Language: en' -H 'Accept: application/json, application/linkset+json;q=0.9, */*;q=0.5' "$ORIGIN$p" | jq -c '{issuer,token_endpoint,resource,authorization_servers}' 2>/dev/null || echo "missing or not JSON"; done

Read the oauth-discovery check page for its sources and the change to make.

Questions about the OpenAPI checker

Can I paste an OpenAPI document?

No. It checks the document your site publishes, where a client looks for it: a pointer the site advertises, or one of the 5 standard paths /openapi.json, /.well-known/openapi.json, /openapi.yaml, /api/openapi.json, and /swagger.json.

Why does my result say out of scope?

These are checks of the API and agent module. The score counts that module only when the scan finds an API or agent surface. On a site with none, the report marks each of them out of scope and says why. oauth-discovery also waits for OAuth. It is asked only of a site where the scan saw OAuth in use: discovery metadata, a Bearer challenge, or an OAuth security scheme in its OpenAPI document.

How do these checks count in the score?

openapi, api-catalog, docs, and oauth-discovery are in the web-standards part: 70% of the score, and the one part whose checks hold a level. The methodology says what each state earns.

Why does it run the full scan?

The form starts the same scan as /scan, so the result is a scan record with a fingerprint you can verify. The report opens on openapi, api-catalog, docs, and oauth-discovery, and the full report follows. A stored record younger than 6 hours opens instead of a new scan.

Read next

• MCP server vs API, skills, WebMCP, A2A

Related checks in the rubric:

• mcp-server: MCP server answers and lists its tools
• status-page: Service status and changelog feed
• auth-md: /auth.md agent authentication guide

The methodology is the scoring contract for all 60 checks, including the rule for a site that is not measured.