# OpenAPI for agents — machine-readable API contracts

> An OpenAPI description tells an agent exactly how to call an API: endpoints, parameters,
> responses. The difference between an API that exists and one an agent can use.

- status: verification lands with the next crawl (September 2026); entries will be dated
- discovery we test: /openapi.json at a predictable URL, or specs linked from an
  RFC 9727 API catalog at /.well-known/api-catalog
- verified entries: 0 today — declared, then verified, never assumed

## How Known-Good verifies it

The probe fetches /openapi.json and every spec an API catalog references, checks each
parses as OpenAPI, and records version, endpoint count, and the date. A 200 that returns
an HTML error page fails — it sends an agent down a path that breaks. Auth-gated APIs are
recorded honestly as keyed doors: present, and marked as needing credentials.

## Publishing yours

    /openapi.json                the spec itself, at a predictable URL
    /.well-known/api-catalog     an RFC 9727 catalog linking every spec you publish

Then request a probe: https://knowngood.sh/submit — the probe decides, never the request.

## Related

- Search the index: https://knowngood.sh/ (REST /api/find · MCP /mcp)
- Working MCP servers: https://knowngood.sh/mcp-servers
- Rubric and tiers: https://knowngood.sh/benchmark