The State of Agent-Readiness 2026

The next wave of software is built by agents.

Agents read documentation, choose an API, and wire it up while their human drinks coffee. We measured 395 of the world’s most important APIs the way an agent experiences them. Here is what we found.

30%of the world’s top APIs are agent-ready.

Every public API on earth just acquired a new kind of user. It never attends your webinar, never squints at your quickstart, never forgives a broken link. It reads what you published, decides in seconds, and moves on. This is a channel problem, not a cosmetics problem: somewhere right now an agent is picking between your API and a competitor’s, and the one it can read wins the integration and the workload behind it.

The number above is behavioral. We handed real models each API’s public documentation surface, the pages an agent actually fetches, gave them real tasks, and graded the answers mechanically. There are no surveys, checklists, or opinions about prose in it, only what a model did with what you published. How the instrument works.

The stakes are economic before they are technical. Agent workloads are high-volume, every token is unit cost, and standard practice is to route each task to the minimum viable model, the cheapest one that clears the bar. That single habit turns readability into a commercial property. The Model Context Protocol does not make this moot: MCP changes how a finished integration calls your API at runtime, not how integrations get chosen and built, and an MCP server is itself a public surface an agent has to discover and understand.

The rest of this report shows you what the agents see.

Key findings

  1. Most top APIs are usable by agents with friction. Few are ready.

    We gave AI models real jobs to do using only each API’s public documentation, then scored the result from 0 to 100. 30% of the APIs we could score reached the level we call agent-ready. The typical API landed in the Legible band: usable, with real gaps. 12% were Opaque, meaning an agent can barely use them, and 70 could not be read in the first place.

    The verdict →

  2. A famous API gets a head start. Good documentation closes the gap.

    Models already know popular APIs from their training, so a well-known API starts ahead on understanding. That head start does not help an agent find an API, and it is not destiny: reading the docs raised the typical API’s score by 8 points, and 80 little-known APIs were carried by their documentation alone.

    Fame vs docs →

  3. Some documentation lets an agent invent a feature that does not exist.

    We asked models to do things each API cannot do. 4% of scored APIs have documentation that let the model confidently write a request for a feature that was never there. In a real product that is a failed call and a confused customer.

    Trap tasks →

  4. Readability has a price, and most APIs are expensive.

    Companies route routine agent work to the cheapest AI model that can handle it. Only 4% of scored APIs can be used by a small, cheap model; 10% need the most expensive tier, which makes them easy to route around. Even within one category, the hardest API to understand takes 7.4 times more reading than the easiest.

    Cost of comprehension →

  5. Agents struggle more to find APIs than to read them.

    Before it reads a word, an agent looks for a few standard files that say where the documentation is. Most APIs read well once found: the typical score for understanding an API is 75 out of 100, for finding it 47. Only 3% of APIs publish an AGENTS.md, the simplest of those files.

    Discovery →

  6. The problems repeat, and each one has a known fix.

    Most lost points come from a handful of documentation gaps: an unclear base URL or auth method, an incomplete spec, an agent-facing index that points nowhere, missing features that are not marked as missing. None of it is a rewrite, and a free scan shows which ones apply to your API.

    What to do →

Agent-ready means Clear or above on the Discry Score, the behavioral instrument described in Chapter 2. Bands, edges, and the full method: methodology.

  • 395APIs measured
  • 324scored on the Discry Score
  • 70unreachable or blocked to agents
  • 67.7median Discry Score, out of 100
02 · THE INSTRUMENT

Measured, not judged.

Every grade in this report is a model’s real answer to a real task, checked mechanically against the API’s own published spec. The whole method fits in three steps.

  1. The task

    We give a model a real job an agent would face, such as constructing the request that creates a refund, and hand it one thing: the API’s public documentation surface, fetched the way most agents fetch it, over plain HTTP with no JavaScript. Documentation that ships an agent-legible surface (an llms.txt, markdown mirrors) is rewarded for it, and that reward is disclosed.

  2. The answer

    The model answers from those docs: method, path, auth header, parameters, or a fact such as the base URL or what a 429 means. It also cites its source, the exact page and a verbatim quote proving the docs say it.

  3. The grade

    Two mechanical checks. The answer is checked against ground truth extracted from the API’s own spec: the path matches or it does not. Separately, the citation is checked against the page the model claims to have read: the quote has to appear there. Both must clear, even if the model already knew the answer from training. No human judgment touches either check.

Repeat across a published task bank and across runs, take the median, and you get a Discry Score. Every score decomposes into discovery (can agents find you) and comprehension (can agents understand you), and no number in this report appears without that split behind it.

One boundary, stated plainly: no call is ever sent. The instrument measures what an agent can find, understand, and construct before execution, from the public surface alone. Authentication, live calls, reliability, and runtime behavior are out of scope by design. That is a different measurement, and nothing in this report speaks to it.

Every number here comes from a single instrument version: all 395 APIs under instrument 3.0.1, task banks 1.3.0, scanned Jul 31, 2026 – Sep 7, 2026. No mixed vintages, no legacy scores carried forward. When you compare two APIs in this report, they sat the same exam.

We audited ourselves before we published

Before publication we put the instrument on trial at the trace level, with the failed cells presumed guilty: every failed task in a stratified sample was independently ruled a genuine documentation failure or an instrument error, with the API’s live agent-facing surface fetched as a receipt where it drove the result. No sampled grade was overturned, and every low grade in the sample decodes to a verifiable property of the API’s own documentation surface.

When we say an API’s documentation was unreachable, we show our work. Every such verdict in the Index ships with the exact URLs the instrument tried and what each returned. Read the full methodology, including the published task banks and the appeals path.

Request-construction tasks are graded only where the corpus provides citable ground truth; each profile discloses its coverage as n/5. Profiles below the coverage floor are excluded from rankings and labeled insufficient coverage. Run spread (median of 3) is disclosed per profile.

03 · THE VERDICT

30% of scored APIs are agent-ready. The median lands in Legible.

Here is the whole industry on one exam: 324 APIs placed into the 5 bands of the Discry Score, and the 70 we could not read at all. Discry your API to see where it lands.

68
median Discry Score
  1. SharpAgents read these docs at full fidelity237%
  2. ClearReadable with minor friction7323%
  3. LegibleUsable, with real gaps10633%
  4. MurkyAgents misread these docs often8225%
  5. OpaqueEffectively unreadable to agents4012%

A Sharp band means an agent can find your API, understand it, and construct correct requests from your public docs alone. A Opaque band means it largely cannot. Between them sit most of the industry’s most important APIs: readable with friction, at a cost the next chapters put a number on.

The top of the Index

These teams built for the new reader. Every name links to its full profile.

  1. 1Firecrawl96Sharp
  2. 2Resend93Sharp
  3. 3talonicdev93Sharp
  4. 4OpenAI91Sharp
  5. 5Razorpay90Sharp
  6. 6AssemblyAI90Sharp
  7. 7Oso89Sharp
  8. 8Together AI89Sharp
  9. 9Cognition88Sharp
  10. 10CircleCI88Sharp

The bottom of the Index

Naming names is the point of an index, and the method chapter is the license. Each of these bands was earned mechanically, links to a trace-backed profile, and has a free fix path.

  1. 324Axelar Network22Opaque
  2. 323SuperTokens24Opaque
  3. 322Basic Machines24Opaque
  4. 321Legends26Opaque
  5. 320fal26Opaque
  6. 318Revolut28Opaque
  7. 318Insightly28Opaque
  8. 317Avalara29Opaque
  9. 316Capsule CRM29Opaque
  10. 315Cypress30Opaque

Some low bands belong to household names whose human documentation is excellent. Cloudinary publishes an llms.txt, the file that tells an agent where to read, and still scores Opaque: the agent-facing surface points at pages that do not answer. The human experience and the agent experience have quietly forked, and only one of them was being tested until now. Memory does not rescue a famous name either. Every open-book answer needs a citation checked against what the instrument actually fetched, so what a model remembers and what it can prove from your docs are graded separately, and only the second counts.

Below the ranks

59 APIs are Invisible to agents: a plain HTTP fetch, the way most agents read, returned nothing usable. 11 more are Walls agents out: the docs refuse automated access. Each is listed with its reason and the URLs we tried, and 1 more are held out of the rankings for insufficient task coverage. Unreachable is a documented verdict, not a euphemism for bad. For an agent, it is functionally identical to not existing.

Invisible to agents 59

Walls agents out 11

04 · FAME VS DOCS

Fame helps an agent understand you. It does nothing to help an agent find you.

Every API sat the exam twice: closed-book, from memory alone, and open-book, with its public docs in hand. The distance between the two is the docs lift, the part of your score you control. Find your API’s lift.

0.55
fame ↔ comprehension
0.16
fame ↔ discovery
+8
median docs lift
Known, and the docs teach more 104Unknown, carried by the docs 80Known by heart, docs add nothing 93Unknown, and the docs do not help 47
Familiarity: closed-book pass rate →Docs lift: open-book gain, points →

Familiarity predicts comprehension. The rank correlation between an API’s closed-book pass rate and its comprehension score is 0.55; against its discovery score it is 0.16. A model may already know Stripe’s request shapes by heart from years of tutorials and example repos. It does not know where your llms.txt is.

The head start is real, and you cannot blog your way into a training corpus by next quarter. The same data says it is not destiny. The median docs lift across the corpus is 8 points, and the less a model already knows an API, the more its docs move the score: the correlation between familiarity and lift is -0.44. 80 APIs the models had barely heard of were lifted by their documentation alone, 18 of them into the top two bands; Excalidraw gained the most. Fame is inherited. Readability is shipped.

The opposite corner carries its own risk. 93 APIs score from memory and gain nothing from their docs; Parallel is the clearest case. Today’s score is yesterday’s training run, and it decays from the moment the API changes.

Checklist scanners and docs platforms cannot produce this chart. It only exists when you test real models against the docs and measure the difference.

05 · TRAP TASKS

4% of scored APIs let a model build a request for a capability their docs never describe.

Alongside the real tasks, every exam includes trap tasks: requests for capabilities the API does not have. Most documentation passes them. The docs that fail ship the failure every engineer has been burned by.

4%
of scored APIs failed a trap task

What a failed trap looks like at the trace level. Real task, real model output, API redacted.

// trap task: the reachable docs surface attests no such capability
// ground truth: unsupported · docs surface attests nothing for it

POST /api/1/send
Authorization: Basic <base64(key_id:key_secret)>
Content-Type: application/x-www-form-urlencoded

{"amount":"0.01","currency":"XBT","address":"<external_bitcoin_wallet_address>"}

// model's citation: [redacted]/en/developers/api
// "Send post Send get List supported networks…"
// verifies against nothing the instrument fetched: recalled, not read.

// verdict: FAIL: attempted an unsupported capability instead of refusing (hallucinated call)
// model: frontier model · API [redacted]

The agent does not say it cannot find the capability. It says here is the call: fluent, plausible, correctly formatted, for something the documentation in front of it never attested. A well-built documentation surface lets the model check its confidence through scoped references, an honest capability map, and a spec that makes absence visible. A poor one leaves it to improvise from pattern memory. The grade is mechanical: either the docs stopped the confabulation or they did not.

Everything about the request above is professional: the verb, the path, the auth header, the encoded body. What it lacks is grounding. The model cites a passage from a page it never fetched, so the citation is recall dressed as evidence. That is why the strongest model can fail a trap where a smaller one refuses: the more an API’s real reference lives in a model’s memory, the more its reachable docs have to do to keep that memory honest.

No call was ever sent. The instrument grades the construction against the API’s own published spec. The hallucination happens on paper, where it is cheap. In your users’ agent stacks it happens in production, where it is not. The fix is to make absence legible, not to write more: a complete spec, a scoped agent surface, and nothing in your docs that invites the model to guess. How trap tasks are built and graded.

06 · COST OF COMPREHENSION

Only 4% of scored APIs can be understood by a small model.

Cost-based routing sends routine agent work to the cheapest model that clears the bar. For every API we asked how capable a model has to be before it reliably completes real tasks from the public docs, and how many tokens it burns getting there. Find your API’s floor.

  1. Small-model readyA small, cheap model completes the tasks from your docs alone.144%
  2. Advanced-model requiredMid-tier models clear the bar; small ones do not.8627%
  3. Frontier requiredOnly the most capable and expensive tier completes the tasks.3410%
  4. Not agent-readyNo tested tier could complete the tasks reliably.8025%
  5. Unmeasured11034%

There is a comfortable assumption in most API teams: the models will get smarter, so this solves itself. The economics run the other way. Agent workloads are high-volume and every token is unit cost, so the frontier model plans and the small, fast model executes. The reader your documentation most needs to satisfy is the most economical model that clears the bar, not the best reader money can buy.

4% of scored APIs are small-model ready: a cheap model completes the tasks from the docs alone, at the economics agent pipelines are tuned for. 27% need an advanced model, usable at a multiple of the cost. 10% need a frontier model, and 25% could not be completed reliably by any tested tier. 34% have no floor reading yet and are shown as unmeasured, never as a floor.

The floor is a property of your docs, not your product. The same API drops a full tier of required capability when its documentation stops making the model infer what it could have stated: clear base URLs, explicit auth, honest examples. Smarter models will not rescue an unreadable API. Cheaper readers will simply skip it.

Every API now has a price of comprehension, denominated in tokens.

Tokens a model consumed per task it passed, cheapest to priciest API inside each category. A payments API is only ever compared to payments APIs.

  1. AI 44
  2. Productivity 26
  3. Payments 30
  4. CMS 16
  5. Communication 29
  6. Commerce 16
  7. Analytics 25
  8. Auth & identity 18
  9. CRM 18
  10. Developer tools 42
  11. Infrastructure 60

Human attention was always the scarce resource documentation spent. It was never on an invoice. Agent attention is: every page an agent must fetch and every tangent it must read past is tokens, and tokens are money and latency. For the first time, how efficiently your documentation teaches has a unit price.

Inside every category the spread is wide. In infrastructure, the priciest API to understand (Axelar Network) costs 7.4 times the tokens of the cheapest (Render) per passed task. The metric quietly punishes marketing prose interleaved with reference material, the same fact stated three ways, and critical parameters mentioned only inside long tutorials. Humans are brilliant at skipping. An agent pays for every token, and so does its operator.

An expensive-to-understand API loses twice: agents that read it burn budget, and cost-aware pipelines have every reason to prefer the competitor that teaches the same job in a fraction of the tokens. Comprehension cost is the closest thing the agent era has to page-load time, invisible to the team that owns it and decisive to the user who pays for it.

Tokens-to-comprehension is a diagnostic, never a score input. Measured on one model version (claude-opus-4-8); the numbers move with model and prompt design.

Capability-floor labels are vendor-neutral: small-model ready, advanced-model required, frontier required. The exact models and versions tested behind each tier are disclosed in the methodology and in every profile’s provenance.

07 · DISCOVERY

Agents can read most top APIs. Finding them is the hard part.

Everything so far measured what happens after an agent reaches your documentation. This chapter is the step before: the machine-readable signals an agent looks for first, and how many of the world’s top APIs publish them. See who publishes them.

47
median discovery
75
median comprehension
  1. robots.txt allows AI crawlers87%343
  2. llms.txt75%297
  3. sitemap.xml72%285
  4. llms-full.txt47%187
  5. Valid OpenAPI spec43%171
  6. Listed in an MCP registry30%120
  7. /.well-known/mcp.json12%48
  8. AGENTS.md3%12

of 395

Agents do not discover APIs through conference talks or word of mouth. They look for files: an llms.txt (the plain-text index that tells an agent where to read), a valid OpenAPI spec (the machine-checkable contract), an AGENTS.md, an MCP manifest, a robots policy that does not shut out AI crawlers. These are cheap to ship and standardized.

The most published signal is robots.txt allows AI crawlers, at 87% of the corpus. The rarest is AGENTS.md, at 3%. A valid OpenAPI spec, the file that lets an agent construct a request without guessing, is published by 43%. A published llms.txt is no guarantee either: the median discovery score across the corpus is 47 against 75 for comprehension, because many of those files point at pages that do not answer. Some of the Opaque bands in Chapter 3 are exactly this: strong human docs behind an agent-facing surface that leads nowhere.

The objection this report hears most: MCP

The Model Context Protocol is the clearest bet on how agents will consume APIs next, a first-class, tool-shaped surface instead of scraped prose. It is also the objection this report hears most: with MCP, documentation should not need grading. MCP changes how a finished integration calls your API at runtime. It does not change how integrations get chosen and built. The coding agents scaffolding software on top of APIs today have to understand your endpoints, your auth, and your request shapes from your documentation before any tool surface enters the picture. And an MCP server is itself a public surface an agent must discover: the discovery problem moves into a manifest, it does not disappear.

So we counted two separate doors. 30% of top APIs are listed in a public MCP registry. 12% publish a first-party manifest at /.well-known/mcp.json. Only 18 APIs have both. A registry listing is often community-built and says nothing about whether the API’s own surface points an agent at it; the manifest is the front door the API itself controls, and it is the rarer of the two. Either earns discovery credit in this Index. MCP quality is where the next edition of this measurement is headed.

08 · WHAT TO DO

Most agent-readiness failures are a handful of fixable patterns.

If this report has a consoling finding it is this: the failures repeat. Across 324 scored APIs, most lost points trace back to a few patterns, and every pattern has a known fix. Start with your own number.

  1. No AGENTS.mdFix: publish one that points at the reference97%313
  2. No /.well-known/mcp.jsonFix: publish a manifest for the MCP surface94%306
  3. No public or valid OpenAPI specFix: publish and validate the spec80%259
  4. No llms-full.txtFix: ship the full-text mirror47%153
  5. No sitemapFix: publish one that covers the reference44%141
  6. Factual recall failuresFix: state base URL, auth, and limits in one place42%128

of 324

All of it is documentation engineering: make the base URL and auth scheme unambiguous, keep the spec complete and valid, publish an agent-facing surface that actually answers, make absent capabilities legible, and stop making a paying reader parse marketing.

Start with your own number

Drop your API’s docs URL and get your Discry Score, with discovery, comprehension, capability floor, and the specific failures behind each, in about a minute. Free, no signup. Discry your API.

Install the Index in your agent

The Discry Index is built to be read the way it measures, by agents. Every profile ships as machine-readable markdown and versioned JSON, and the Discry MCP server puts the full Index inside your agent, so which payments API this agent should build on can be answered from measurement instead of memory. Install the Discry MCP server, or start from llms.txt and /api/v1.

Take the dataset

The aggregate dataset behind this report, every score, sub-score, signal, and ranking, is published under CC-BY. Cite it, build on it, argue with it; attribution is the only ask. Download it as CSV or JSON.

Explore, compare, dispute

Browse the full Index and its category leaderboards, or put any two APIs side by side. If you think your band is wrong, the appeals path is a rescan: same instrument, fresh crawl. Free scans run against a different environment than the standing Index; the methodology carries the full disclosure.

This edition is a snapshot: all 395 APIs under one instrument, one scan window. The next one is a delta. Every API here is re-measured as the Index rescans, and the Q4 2026 edition ranks the movers: who climbed, who slid, and which fixes paid. The scoreboard is live from today. What it shows next quarter is up to the teams in it.

We are building toward that edition with a design-partner cohort, a small group of API teams working the fix list with us between editions.