What Is API Agent-Readiness? The Complete Guide

Agent-readiness is whether an AI agent can discover, understand, and correctly call your API from its public documentation surface — the pages, specs, and entry-point files an agent actually fetches. An agent-ready API can be found by a model that has never seen it, understood from the docs alone, and called correctly on the first attempt. An API that fails any of those three steps loses the integration before a human ever opens the docs to evaluate it.

This guide defines the term, explains the two axes it decomposes into, describes how it can be measured rather than asserted, and lays out what to do about it, in priority order.

The definition, in plain terms

When a developer asks a coding agent to integrate an API, the agent does what any integrator does, compressed into seconds: it looks for the documentation, reads what it can retrieve, and writes code based on what it understood. Every step of that sequence can fail quietly.

• Discovery can fail: there is no machine-readable entry point, the docs render empty without JavaScript, or the entry point that exists routes the agent to marketing pages instead of the API reference.
• Comprehension can fail: the agent retrieves the docs but misreads the authentication scheme, guesses at endpoint shapes, or confidently invents a capability the API does not have.

Agent-readiness names the property of surviving both. The concept pairs with a measurement: the Discry Score, which always decomposes into those same two dimensions — discoverability and comprehension — so a team can see which one it is losing on.

One boundary matters from the first paragraph onward. Agent-readiness is a property of the public documentation surface, measured before execution. It says nothing about whether your API is reliable, whether your SDK is good, or whether authenticated calls succeed at runtime. Those are real qualities, and they are downstream: an agent that never finds your docs, or misunderstands them, never reaches the point where runtime quality matters.

Why it matters now

AI agents have become a working consumer of API documentation. Coding assistants scaffold integrations daily, and every scaffold attempt is a model reading your docs and acting on what it understood. When that reading goes wrong, the failure shows up in observable places: a developer asks an agent to integrate an API, the agent hallucinates an endpoint, and the resulting support ticket blames the API rather than the agent.

For the team that owns the API, this creates a concrete problem with no established playbook. "Make us AI-ready" arrives as a mandate with no definition of done. Shipping an llms.txt or an MCP server without a way to verify it worked is cargo-culting; the file exists, and nobody knows whether an agent can actually use it. Agent-readiness, defined as above, turns the mandate into something checkable: specific signals an agent either finds or does not, and a comprehension level a model either reaches from your docs or does not.

The stakes are practical rather than apocalyptic. Agents do not need to run the economy for this to matter; they only need to keep doing what they already do — reading public docs and writing integration code — for the legibility of those docs to decide which APIs get built on. The docs are the interface an agent sees, and for a growing share of integration attempts, the only one.

The two axes: discovery and comprehension

The two failure modes happen in order, so the measurement is organized the same way. Discovery is the gate; comprehension is the test you get to take if you pass it.

Discovery: can agents find you?

Most agents fetch over plain HTTP without executing JavaScript, and they navigate by machine-readable entry points rather than by browsing. The discovery layer is the set of conventions that make an API findable on those terms:

• llms.txt — a plain-text index at your docs root that tells agents which pages matter, defined by the llms.txt convention. This is the single highest-leverage discovery file; our guide to what llms.txt is and why your API needs one covers writing a good one, and the llms.txt examples gallery shows real files from the APIs we scan.
• llms-full.txt — the companion full-text bundle: your core docs as one file an agent can load in a single request instead of crawling page by page.
• AGENTS.md — the brief that coding agents check for how to work with your system: conventions, auth setup, the golden-path example, common mistakes. See AGENTS.md for APIs for what belongs in it, and the AGENTS.md examples gallery for real ones.
• An OpenAPI spec — a parseable, publicly fetchable OpenAPI document is the closest thing to ground truth an agent can get about your endpoints, parameters, and shapes.
• An MCP manifest — a .well-known/mcp.json at a well-known path, declaring a Model Context Protocol surface an agent can wire up.
• MCP registry presence — a listing in a public MCP registry, so agents searching for a server under your name can find one.
• robots.txt — the robots exclusion protocol applied to AI crawlers: whether your rules allow agents to read the docs at all, or blanket-block every bot including the ones building integrations.
• A sitemap — a sitemap that actually includes your documentation pages, so an agent can enumerate the docs surface instead of guessing at URLs.

Each of those is a check-level fact about your public surface: the file exists and works, or it does not. That verifiability is what makes discovery the tractable half of the problem — and the half where the observed failures are most avoidable. Across the APIs we scan, the recurring patterns are specific: llms.txt files that index the company's marketing site and never link the API reference; site-wide llms.txt dumps hundreds of kilobytes long that bury the docs under blog posts and legal pages; developer portals that render essentially nothing without JavaScript, leaving robots.txt and sitemap requests returning empty shells; docs that live on a subdomain the main site's sitemap never mentions. In each case the API loses the agent before its documentation quality is ever tested.

Comprehension: can agents understand what they find?

Discovery gets an agent to your docs. Comprehension is whether it can operate your API from them: identify the authentication scheme, construct a correct request, follow a multi-step workflow, recover from a documented error, and — just as important — recognize what your API does not do instead of inventing it.

Comprehension failures are harder to see than discovery failures because the docs look fine to the humans who wrote them. Documentation that reads well to a person who already knows the product can still be opaque to a model encountering it cold: endpoint descriptions that state shape without purpose, examples that don't run, workflows implied but never written down, capability boundaries left to inference. The gap between "our docs are good" and "a model reading our docs cold gets the request right" is exactly what agent-readiness measures on this axis.

Comprehension also has a cost dimension. Routing routine work to lower-cost models is standard industry practice, which means the model reading your docs is often a small one. The capability floor captures this: the lowest tested model tier that reliably operates your API from its documentation, labeled small-model ready, advanced-model required, or frontier required. Docs that only a frontier model can operate are effectively invisible where the volume is.

How agent-readiness is measured

A checklist can tell you a file exists. It cannot tell you whether an agent that reads your docs gets your API right. So the comprehension axis is measured behaviorally: behavioral measurement means real models are quizzed on your live documentation and their answers are graded, rather than your docs being audited against a rubric of best practices.

The instrument works like an experiment:

• Models are quizzed from published task banks — factual questions an integration depends on (auth, errors, pagination, limits), request-construction tasks, and workflow questions — with your fetched docs as their only source.
• Grading is mechanical. Answers are checked against ground truth that must cite a specific location in your own documentation. No human judgment call decides whether a model "basically got it."
• A closed-book baseline controls for fame. Every task first runs without your docs. Anything a model already knew from training is excluded, so a famous API earns nothing from being famous and an obscure one loses nothing for being obscure.
• Docs lift is the quantity that matters: how much better models perform with your documentation in hand than without it. That difference is the measured contribution of your docs — the thing you actually control.
• Trap tasks probe invention. Some tasks ask for things your API does not support, and the correct answer is a refusal. A model that confidently fabricates an endpoint under your docs' influence is a documented comprehension failure, and it is the same failure that generates hallucinated-integration support tickets in the wild.

The full instrument — including the plain-fetch policy, the contamination guard, and the published receipts behind every result — is documented on the methodology page. The output is visible on any published profile: see how the decomposition reads for Stripe, Twilio, or Resend, each with the fetched URLs and check results behind it.

What to do about it, in order

The two axes have very different costs, which sets the priority order.

Start with discovery. Discovery signals are files: cheap to ship, verifiable the moment they exist, and the difference between an agent finding your reference and finding nothing. Ship a focused llms.txt that routes to your API reference (the examples gallery shows what focused looks like), an AGENTS.md that briefs a coding agent on the golden path, and a publicly fetchable OpenAPI spec. Check that your robots.txt is not blanket-blocking AI crawlers and that your sitemap includes the docs subdomain. If you expose tools, add a .well-known/mcp.json and get listed in an MCP registry. One caution from the observed failure modes: an llms.txt that points agents at marketing pages is worse than none, because it is treated as your declared agent-facing entry point.

Then tighten comprehension. Rewrite endpoint descriptions to be task-oriented, make examples realistic and runnable, document multi-step workflows end to end, write real error-recovery guidance, and state capability boundaries explicitly so a model can refuse what you don't support instead of inventing it. The prioritized version of this work, including what typically moves the measurement most, is in how to make your API agent-ready.

Then defend it. Agent-readiness regresses silently: a docs-platform migration drops your llms.txt, a refactor moves the reference off the sitemap, and nothing alerts you. Treat the signals as production surface and re-verify them on a schedule.

Where the market stands today

Adoption across the Discry Index corpus shows a market that has adopted the first-wave signal and stalled on the rest.

Permission is largely a solved problem: 80% of scanned APIs serve a robots.txt that allows AI crawlers. The map is what's missing. llms.txt has crossed into the mainstream at 64% adoption — but its companions lag well behind it: 31% serve an llms-full.txt and only 30% publish an AGENTS.md.

That gap is the current shape of the problem. llms.txt is the signal with two years of advocacy behind it, and most teams have shipped one. AGENTS.md is the signal aimed at the agents actually scaffolding integrations today, and two-thirds of the market hasn't shipped it. The basics are similarly unfinished: only 54% of scanned APIs expose a publicly fetchable, parseable OpenAPI spec and 65% have a sitemap that includes their docs pages.

The MCP numbers tell the same story from an unexpected angle. 76% of scanned APIs show up in a public MCP registry — largely because community-built servers get listed whether or not the API producer was involved — while only 5% serve their own .well-known/mcp.json manifest. The ecosystem is building agent surfaces for APIs faster than API producers are claiming them.

For a team deciding where to invest, the read is straightforward. The crowded signal (llms.txt) is table stakes you should still ship well, and the uncrowded signals (AGENTS.md, a first-party MCP manifest) are where a modest effort currently separates you from two-thirds or more of the market. Discovery is checkable today, comprehension is measurable today, and both are earlier than the noise around them suggests.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.