# OpenAPI definition

> OpenAPI definition: A machine-readable contract so an agent can discover your API and generate correct calls. The fix: publish an OpenAPI definition.

- Source: /checks/openapi
- Site: AgenticWebScore
- Language: English

---
A machine-readable contract so an agent can discover your API and generate correct calls.

| 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:

```bash
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.

```json
{
  "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" } } }
          }
        }
      }
    }
  }
}
```

> A valid document scores nothing on its own: if neither the homepage, a Link header nor your api-catalog points at it, no agent will ever request it.

## 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 | — |