Protocol Discovery · Essential · High impact
OpenAPI definition
A machine-readable contract so an agent can discover your API and generate correct calls.
- Essential
- High impact
- Adopted standard
| Property | Value |
|---|---|
| Check id | openapi |
| Dimension | Protocol Discovery (25%) |
| Tier | Essential — pool 80 pts |
| Weight inside tier | 2 |
| Impact | High |
| Maturity | Adopted — A ratified standard with real deployment. |
| Conditional | No |
| Publishing skill | openapi |
| Standards | OpenAPI 3.x |
What is measured
The scanner fetches the homepage and follows whatever pointer to an API description the site advertises (a service-desc link from your api-catalog, a Link response header, or a link in the HTML), then parses the target. It passes when that document is OpenAPI 3.x: an openapi version string, info.title, info.version and a non-empty paths object. It partially passes when the document parses as OpenAPI but paths is empty, or when the advertised URL returns a human-readable description or a 404.
Reproduce it yourself
You do not have to take our word for any of this. Run the same measurement against your own domain:
DOMAIN=https://your-domain.example
curl -sS "$DOMAIN/.well-known/api-catalog" -H 'Accept: application/linkset+json' | jq -r '.linkset[]["service-desc"][]?.href' | while read -r u; do curl -sS "$u" | jq '{openapi, title:.info.title, version:.info.version, paths:(.paths|keys|length)}'; done
The fix
This is the artifact to ship. It is the complete change, not a description of one.
{
"openapi": "3.1.0",
"info": { "title": "Example Public API", "version": "1.4.0" },
"servers": [{ "url": "https://api.your-domain.example/v1" }],
"paths": {
"/orders/{orderId}": {
"get": {
"operationId": "getOrder",
"summary": "Get the status of one order",
"parameters": [
{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "The order",
"content": { "application/json": { "schema": { "type": "object" } } }
}
}
}
}
}
}
Standards referenced
-
OpenAPI 3.x
Related checks
| Check | Tier | Impact | Same skill |
|---|---|---|---|
mcp-card — MCP server card | Essential | High | — |
oauth-discovery — OAuth discovery documents | Essential | High | — |
api-catalog — API catalog | Recommended | Medium | — |
agent-skills — Agent Skills declaration | Recommended | Medium | — |
a2a-card — A2A agent card | Recommended | Medium | — |
a2a-signed — Cryptographically signed agent card | Emerging | Medium | — |
auth-md — /auth.md agent authentication guide | Emerging | Medium | — |
webmcp — WebMCP browser tool declaration | Emerging | Medium | — |