Public OpenAPI Document So AI Agents Can Auto-Generate Tool Definitions
A single discoverable file that lets any AI agent learn your API and call it without bespoke integration.
What this signal tests
We check whether your site publishes an OpenAPI document - the industry-standard machine-readable description of an API - at a conventional path such as /openapi.json or /.well-known/openapi. The document must be valid OpenAPI 3.x or the older Swagger 2.0, parseable as JSON or YAML, and contain at least one declared API path.
Why it matters for your visibility in AI
OpenAPI is the single most important file an AI agent can find on a site that has an API. Every major agent framework - OpenAI function-calling, Claude tool-use, LangChain, the Model Context Protocol (MCP) ecosystem, and Microsoft Copilot - can read an OpenAPI document and automatically generate the tool definitions an agent needs to call your API safely. No human integrator, no custom code, no per-agent wrapper. The practical consequence is that if a customer asks their AI assistant to do something that your API supports - fetch their balance, place an order, look up shipping - the assistant succeeds only if it can find your OpenAPI. Without it, agents either fall back to web scraping (slow, brittle, often blocked) or simply skip your service. Publishing OpenAPI is the cheapest single thing most API providers can do to be agent-ready.
Pass criteria at a glance
| Criterion | Passes when |
|---|---|
| At least one path returns valid OpenAPI 3.x or Swagger 2.0 with non-empty paths. |
How we test it
Our scanner fetches each of the conventional OpenAPI paths - /openapi.json, /openapi.yaml, /swagger.json, /api/openapi.json, and /.well-known/openapi - and also checks for a Link header with rel=service-desc on your API responses. When it finds a candidate, it parses the document, confirms a top-level openapi or swagger version field, and verifies the paths object is not empty.
Show technical detection method
GET candidate paths; validate JSON/YAML; require openapi or swagger version and 'paths' object. Also accept Link header rel="service-desc".
If your site fails: how to fix it
- If you already have an internal OpenAPI document used for SDK generation or developer docs, publish it at /openapi.json with public read access; this is usually a one-line change to your build pipeline.
- If you do not yet have an OpenAPI document, generate one from your existing code using a framework helper (FastAPI, NestJS, ASP.NET Core, Spring Boot, and most modern stacks emit OpenAPI natively).
- Strip private or admin-only endpoints from the public document so agents only see the surface you are happy for them to call; keep the internal document for your own team.
- Add a Link header with rel=service-desc to every JSON API response pointing at the OpenAPI document so agents discovering an endpoint mid-flow can self-orient.
- Set up a CI check that fails if the deployed OpenAPI drifts from the real routes; stale OpenAPI is worse than no OpenAPI because agents will hit dead endpoints.
Quick facts
| Maturity | ESTABLISHED |
|---|---|
| Weight | high |
| Category | Agent Actions |
Primary sources
Related signals
Frequently asked questions
Does publishing OpenAPI expose us to abuse?
It exposes the same surface that any motivated attacker could enumerate today. The right protection is authentication, rate limiting, and input validation - not obscurity. Publishing OpenAPI does not bypass auth; it just documents the requests an authenticated caller can make.
What if our API requires keys or accounts?
Publish the OpenAPI document publicly with the auth scheme described in securitySchemes. Agents can read the schema even without a key; they then prompt the user for credentials or follow the OAuth flow you declare. Keeping the schema secret does not protect the API.
Does this cost anything to implement?
If your framework already emits OpenAPI, publishing it is essentially free - a configuration change. If you need to generate it from scratch, the cost is a few engineering days for a typical API. There are no licensing fees and no recurring costs.
How is OpenAPI different from MCP?
OpenAPI describes a traditional HTTP API. MCP is a newer protocol designed specifically for agent tool-use, often built on top of an OpenAPI definition. Most teams publish OpenAPI first and then expose an MCP server later; the two are complementary, not exclusive.
Run your own scan
Run a free scan and see how your site grades across all 155 AI-readiness signals.