OpenAPI Specs Are the Single Biggest Factor in Agent Readiness (D2 = 15%)
Of the 9 dimensions in the Agent Readiness Score, D2 API Quality is weighted highest at 0.15. That is more than security (0.12), more than reliability (0.13), more than any other factor. Companies with a published OpenAPI spec consistently score 60+. Companies without hit a ceiling around 45. One file fixes more than any other single change.
The Weights: D2 Beats Every Other Dimension
The Agent Readiness Score is a weighted average across 9 dimensions. The weights are not arbitrary — they reflect how much each factor contributes to an agent's ability to actually transact with a business. Here is the full breakdown, ranked.
The math: D2 at 0.15 means a perfect 10/10 on API Quality alone contributes 15 points to your score. A zero there subtracts 15 from your ceiling. No other single dimension has that kind of leverage. And the single biggest signal the scanner uses to assess D2 is whether you have a published OpenAPI spec.
The Ceiling: What the Data Shows
Across 500 business scans we see a clean pattern: businesses with a published OpenAPI spec land in a different score band entirely from businesses without one. The boundary is sharp — almost binary.
Real examples: Resend publishes a clean OpenAPI 3.1 spec and scored 75 — the only Gold on the leaderboard. Stripe's OpenAPI spec is famous in the industry and they scored 68. GitHub publishes one (67). Vercel publishes one (70). Supabase publishes one (69). The top of the leaderboard is openapi.json all the way down.
The ceiling for companies without a spec is not a hard wall — you can still score 50 or 55 with excellent work on other dimensions — but going past 60 consistently requires clearing D2. And D2 at 8-plus requires a spec.
What an OpenAPI Spec Unlocks for Agents
An OpenAPI spec is not just documentation. It is a machine-readable contract that gives agents five superpowers they cannot get from any other source.
Discovery
Agents find your spec at /openapi.json and know exactly what operations you support. No scraping, no guessing, no training data required.
Automatic client generation
Any agent framework can generate a typed client from your spec in seconds. openapi-generator, swagger-codegen, Kiota — all work instantly.
Schema validation
Agents validate requests against your schema before sending. Fewer failed calls. Better error signals. Faster iteration loops.
Semantic understanding
Descriptions on operations, parameters, and responses let agents reason about what each endpoint does — not just how to call it.
Versioning and changelogs
OpenAPI specs are diffable. Agents can detect breaking changes programmatically. You ship better, they upgrade automatically.
The Smallest Useful OpenAPI Spec
You do not need to document every internal endpoint. This 30-line example is enough to move D2 from near-zero to 6/10 and push most businesses over the Silver threshold.
{
"openapi": "3.1.0",
"info": {
"title": "Joes Pizza API",
"version": "1.0.0",
"description": "Public API for Joes Pizza menu and ordering"
},
"servers": [{ "url": "https://api.joespizza.com/v1" }],
"paths": {
"/menu": {
"get": {
"summary": "Get the full menu",
"description": "Returns all available items with prices",
"responses": {
"200": {
"description": "Menu items",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Menu" }
}
}
}
}
}
}
},
"components": {
"schemas": {
"Menu": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"price": { "type": "number" }
}
}
}
}
}
}
}
}That is it. Serve it at /openapi.json, link to it from your agent-card.json, and an agent can now discover that you have a menu endpoint, what it returns, and how to parse it — all without reading a single line of human documentation.
How to Ship an OpenAPI Spec (6 Steps, ~2 Hours)
Pick a source of truth
Either (a) hand-write openapi.yaml in your repo, (b) generate from code annotations (FastAPI, NestJS, Spring generate specs automatically), or (c) use a tool like Stoplight or Postman to author visually. Option (b) is the cheapest over time.
Host it at /openapi.json
The conventional path. Serve it with CORS enabled so browsers and agents can fetch it. Add /swagger.json as a redirect — some tools still look there first.
Validate with swagger-cli
Run `swagger-cli validate openapi.json` in CI. Catches missing descriptions, broken $refs, and schema errors before they ship. A 20-line GitHub Action is enough.
Link from agent-card.json
Your agent-card.json should reference the spec URL under the capabilities block. This is the primary discovery path for agents. Without this link, agents that find your card still cannot call your API.
Reference in llms.txt
Add a line to your /llms.txt: "OpenAPI spec: https://example.com/openapi.json". Large language models crawling llms.txt will index and remember your endpoints.
Publish a human version at /docs
Redoc, Scalar, or Swagger UI render an interactive docs page from your spec. Same source of truth, no maintenance overhead. Humans and agents stay in sync.
Tools That Generate OpenAPI for You
You do not have to hand-write YAML. Most modern backend frameworks generate OpenAPI specs automatically from your code. Here are the best options by ecosystem.
The cheapest long-term path is to pick a framework that generates the spec from your code (FastAPI, NestJS, Hono+Zod, Spring). That way the spec and the implementation can never drift. Every new endpoint you add automatically becomes part of the agent-facing contract.
Four Common Mistakes That Waste a Good Spec
Hosting it behind auth
A spec agents cannot fetch is useless. Serve it publicly. If the endpoints are authenticated, let the spec describe auth — but the spec file itself stays public.
No descriptions on operations
summary and description fields are what let agents understand *what* an endpoint does, not just how to call it. Missing descriptions drop D2 from 9 to 5.
Stale specs that drift from reality
If the spec says an endpoint returns { name, price } but actually returns { title, cost }, agents fail silently. Generate from code, not hand-written docs.
Missing error schemas
Specs that only document 200 responses are half-specs. Agents need to know what 4xx and 5xx responses look like to handle failures. Always document the error shape.
Frequently Asked Questions
Why is D2 API Quality weighted higher than security or reliability?
D2 API Quality is weighted 0.15 — higher than D7 Security (0.12), D8 Reliability (0.13), or any other dimension — because the API is the primary interface agents use to interact with a business. A reliable service with no API is useless to an agent. A secure service with no API is useless to an agent. Only an accessible, well-described API enables agent interaction at all. Security and reliability matter, but they are multipliers on top of API quality — not substitutes for it.
Will an OpenAPI spec alone push me to Silver?
Usually, yes. Publishing a valid OpenAPI spec moves D2 from near-zero to 8 or 9 out of 10, which alone adds 10-15 points to your total score. Combined with linking the spec from agent-card.json and llms.txt, you typically move from the 40s into the 55-65 range, clearing the Silver threshold. Companies that score above 70 usually also have OAuth, public status pages, and a changelog — but those build on top of the OpenAPI baseline.
OpenAPI 3.0 or 3.1?
Prefer 3.1 if your tooling supports it. OpenAPI 3.1 is aligned with JSON Schema 2020-12, which makes it easier for agents to validate and reason about responses. Most modern tooling (FastAPI, Stoplight, Redocly) supports 3.1. Older ecosystems still default to 3.0, and 3.0 is fine — it is 99% of the way there. Do not let the version question stop you from shipping.
How detailed does the spec need to be?
Detailed enough that an agent can call your API without reading human docs. That means: every operation has a descriptive summary and description, every parameter has a type and description, every response has a schema, and every error has an example. Skip optional fields at first. A barebones spec that describes 80% of your endpoints well beats a comprehensive spec that describes 100% of them shallowly.
Do I need to publish my internal APIs?
No. Only publish the endpoints you want agents to use. The OpenAPI spec acts as a contract — anything in it is a public commitment. Many companies publish a public/external spec separately from their internal one. You can use OpenAPI tags to separate sections, or maintain two files that share common components via $ref.
See your D2 score in 60 seconds
Run a free Agent Readiness Scan to see your D2 API Quality score — and exactly what to add to move it. Most businesses move from Bronze to Silver by shipping a single openapi.json.