Methodology

What Makes an API AI-Ready?

An AI-ready API is one an agent can discover, interpret, and operate on its own, with no human in the loop. That's a higher bar than good developer experience: a developer can fill the gaps by emailing support or asking a teammate, but an agent only has what's machine-readable. AI-readiness measures how much of your API an agent can use without help.

How We Built This

We worked backward from the APIs agents already integrate best, like Stripe, Twilio, and Anthropic, and checked every signal against current research: MCP tool-definition requirements, answer-engine optimization, the RFC 9457 error standard, and independent audits. The result is surface-agnostic: we never require any single surface. We look across all seven (spec, docs, SDK, CLI, MCP, well-known files, and a Postman collection) and take the best evidence an agent could find.

How Scoring Works

Every check is a concrete, deterministic probe — a parsed schema, a real network response, a fetched error body — and each one ships the evidence behind it. There's no language model in the scoring path, so the same API always gets the same score.

The model is surface-agnostic. A capability counts if any surface proves it, and we take the best evidence an agent could find (best of, never worst of), so a team strong on SDKs isn't penalized for skipping a spec.

Scores sit on a gradient, not a pass/fail line, running from A+ Agent-Optimized, A AI-Ready, B Advancing, C Building, D Emerging, F Not AI-Ready, so even a bare-bones API gets a real score and something to climb toward.

The Seven Surfaces

  • specyour OpenAPI document — fields, schemas, security, servers, responses.
  • docsyour public documentation site, crawled as HTML and .md.
  • SDKyour published client libraries, analyzed statically.
  • CLIyour command-line tool, installed and probed offline.
  • MCPa reachable Model Context Protocol server and its tools.
  • well-knownstandard paths like /.well-known/, robots.txt, security.txt, AGENTS.md, sitemap.
  • collectiona public Postman collection and its test scripts.

API Product Foundations

A well-designed API and good developer experience give both humans and agents the context they need, so you likely already have much of this. It stays in the score because everything an agent does is built on it.

API DesignThe typed, versioned contract agents reason about5 signals

A machine-readable, versioned contract is where everything starts. An agent can't call a function it has no schema for, or handle a breaking change with no declared version. We grade typed schemas, discoverable auth, and governance hygiene.

Machine-readable, versioned contract25%

A current OpenAPI version with a declared versioning scheme lets agents reason about the contract.

  • Valid OpenAPI contractThe spec is a parseable OpenAPI 3.x document.
  • Declared versioning schemeA version is declared and expressed a way agents can detect: a URL like /v1/, a version header, a versioned media type, or a dated version.
  • Self-describing CLIThe CLI emits machine-readable help/schema and reports its version.
Schema coverage & depth25%

Typed, complete request/response schemas are what make agent function-calling possible.

  • Typed requests and responsesOperations declare typed request and 2xx response schemas.
  • Sane schema shapeSchemas aren't pathologically nested or over-complex for an agent to fill.
  • Typed CLI inputsWrite commands expose typed, described fields, not bare strings.
  • Strongly-typed SDK surfacePublic params are fully typed (no any / kwargs), enums are named types, nullability is modeled, and type declarations ship (.d.ts / py.typed).
Auth declared & discoverable25%

Agents can only authenticate when auth is declared, scoped, and discoverable.

  • Auth declared in the contractSecurity schemes are defined and applied to operations, with OAuth scopes described.
  • OAuth discovery metadataWhen OAuth is used, the /.well-known/ authorization-server and protected-resource metadata are served (RFC 8414 / 9728).
  • CLI documents its credentialsThe CLI names the credential env var it needs.
Security & governance hygiene15%

No leaked secrets, no critical lint violations, no OWASP API Top-10 spec smells, and a published vulnerability-disclosure channel.

  • No leaked secretsThe spec contains no real credential-shaped strings.
  • Passes spec lintNo critical API-governance lint violations.
  • Vulnerability-disclosure channelA /.well-known/security.txt with a contact and an unexpired expiry.
Example coverage10%

Examples carry shape semantics schemas under-specify — for humans and agents alike.

  • Examples in the specParameters and responses carry examples.
  • Code samples in docsMulti-language code samples in the documentation.
  • Runnable CLI exampleThe CLI help shows a runnable example invocation.
  • SDK quickstartThe SDK README includes a runnable quickstart.
Developer ExperienceThe onboarding and context that gets integrations working fast5 signals

Humans still choose, integrate, and maintain these APIs. Self-service onboarding, a quickstart, and multi-language samples get them working fast, and they give an agent the context for its first successful request too.

Self-service developer portal29%

Self-serve key/account creation is the fast first call for partners, with no sales gate.

  • Self-serve signupAn account or API key can be created without a sales gate, with a free tier, sandbox, or test mode.
Quickstart present25%

A quickstart is the fastest path from landing page to first successful call.

  • Reachable quickstartA quickstart page with a runnable first-call sample.
Code samples in docs18%

Multi-language samples shorten time-to-first-call.

  • Multi-language samplesCode samples in several languages across the docs.
Description completeness15%

Complete descriptions are the context humans and agents need to use endpoints.

  • Documented operations and paramsMeaningful summaries and descriptions in the spec.
  • Described everywhere elseCLI help, SDK docstrings, and MCP tool descriptions carry real input/output detail.
Changelog published13%

A published changelog lets partners track changes without surprise.

  • Published changelogA changelog is published; a structured feed scores highest.
  • Maintained SDKsOfficial SDK repositories show recent activity.

Agent Journey Optimizations

These categories cover what agents need to succeed with your APIs: how an agent discovers, correctly interprets, and reliably operates them.

Agent DiscoveryWhether agents can find your API at all4 signals

Stage one of the journey. Before an agent can use an API, it has to find it. We grade the machine-readable entry points agents crawl: llms.txt, MCP and package registries, and whether your docs are reachable and un-gated.

llms.txt present, valid & comprehensive30%

A valid, comprehensive llms.txt is the machine-readable entry point for agents.

  • llms.txt front doorA /llms.txt that exists, parses, is advertised from your HTML, covers the docs, and links to clean markdown sized to fit an agent's context.
  • Full-text and SDK llms.txtAn llms-full.txt and an SDK-level llms.txt where applicable.
Docs reachable, not hard auth-gated30%

Agents can only index and fetch docs they can reach — past auth gates and over correct HTTP semantics.

  • Publicly reachable docsDocs aren't behind a login wall, or a machine path exists when auth is required.
  • Correct HTTP semanticsReal status codes, sane redirects, and Accept-header content negotiation that can serve markdown.
Registry & SDK presence28%

Listing in MCP registries and publishing SDKs puts the API where agents and their tooling look.

  • MCP registry listingListed in the official MCP registry with an active endpoint, and an MCP server card at /.well-known/mcp.json.
  • SDKs where agents lookPublished across multiple languages with complete package metadata and an MCP-discoverable surface.
  • A discoverable CLIA released or clearly-documented command-line tool.
  • Indexed for agent toolingPresent in the Context7 documentation index.
Crawlable / AEO12%

Bots allowed plus a fresh sitemap make docs findable by agent crawlers.

  • AI crawlers allowedrobots.txt doesn't block GPTBot, ClaudeBot, PerplexityBot, and peers on your docs.
  • Fresh sitemapA sitemap with good lastmod coverage and recent entries.
Agent UnderstandingWhether agents can correctly interpret what they find6 signals

Stage two. Finding an API isn't the same as using it. We grade RFC 9457 machine-readable errors, operation clarity, structured data, and token-efficient docs. These are the signals that decide whether an agent picks the right endpoint and parses the response without wasting tokens.

Machine-readable errors (RFC 9457)28%

RFC 9457 problem details and a documented error-code inventory let agents parse failures without burning tokens.

  • Problem-detail errors4xx/5xx responses use application/problem+json with RFC 9457 fields.
  • Documented error codesA real inventory of error codes, not a single catch-all.
  • Structured CLI errorsBad input returns a JSON error with a machine-readable fix hint.
  • Typed SDK exceptionsA typed exception hierarchy, with 401 and 403 as siblings so catching one doesn't swallow the other.
Operation purpose clarity25%

Agents select the right endpoint from its summary + operationId; clear, named operations make tool-selection reliable — the strongest driver of correct tool choice.

  • Clear, named operationsOperations have clear summaries and stable operationIds so an agent selects the right endpoint.
Agent-navigable, token-efficient docs22%

Server-rendered, clean, small-footprint docs are what an agent can cheaply fetch and parse correctly.

  • Docs rendering (CSR vs SSR)We fetch your docs the way an agent would and flag pages that only render client-side, since an agent gets an empty page.
  • Markdown availability and parityClean .md versions exist and match the HTML.
  • Clean structureContent starts near the top, headers survive tab flattening, tabs serialize fully, and code fences are valid.
  • Ingestion budgetPages fit an agent's token and size limits with sane cache headers.
Agent instructions file (AGENTS.md)10%

An AGENTS.md gives coding agents explicit setup, auth, and usage instructions to interpret and operate the API — beyond llms.txt's link index.

  • AGENTS.md presentA real AGENTS.md with setup, auth, and usage guidance for coding agents.
Docs structured data8%

Structured data (JSON-LD/schema.org) on docs pages gives agents an unambiguous parse target and is what answer engines cite. Detected on the JS-rendered head (Firecrawl) for a bounded page budget, so JS-injected JSON-LD is now caught; pages we can't render are excluded rather than failed.

  • JSON-LD / schema.orgArticle/TechArticle markup with dateModified that answer engines cite.
Description consistency across surfaces7%

Every surface tells the same story about what the product is.

  • Consistent story across surfacesThe spec, docs, and SDK describe the product consistently, measured by text overlap.
Agent UsabilityWhether agents can operate your API safely and reliably5 signals

Stage three, and the category we weight most heavily. Can an agent operate the API without breaking things? Documented idempotency lets it retry a write without doubling a charge, rate-limit headers let it back off before it gets blocked, and a sandbox lets it try destructive calls safely. This is where integrations actually break.

Idempotency documented27%

Documented idempotency lets agents retry safely.

  • Documented idempotencyMutating operations document idempotency via an idempotency-key param, prose, or an extension.
  • Safe CLI mutationsDestructive commands offer a dry-run and a confirmation guard.
  • SDK retry machineryThe SDK has built-in retry handling.
Rate-limit signaling22%

Machine-readable rate-limit headers let agents throttle adaptively.

  • Rate-limit headersMachine-readable X-RateLimit-*, RateLimit-*, or Retry-After headers.
Pagination documented & consistent22%

Consistent, documented pagination lets agents traverse collections.

  • Consistent paginationList endpoints use a documented, consistent pattern (cursor, offset, or page).
  • Auto-paginating SDKsList methods return auto-paginating iterators.
Sandbox separation20%

An isolated environment lets agents exercise destructive operations safely.

  • Sandbox environmentA test/sandbox environment separate from production, with test credentials.
  • SDK test modeThe SDK exposes a sandbox or test mode.
Runnable collection with test scripts9%

A public, maintained collection with assertions is runnable truth agents validate against.

  • Maintained public collectionA public, recently-updated Postman collection with functional, contract, and security test scripts.

What the Score Doesn't Tell You

The score covers the surface area agents touch, not the overall quality of your product. It measures whether a capability is present, discoverable, and consistent across surfaces, not whether every operation behaves perfectly under every input. A genuinely strong product can still score low because it's hard for an agent to read, and that low score is your map to fixing it.

Being listed in Postman's own catalog earns no credit — it's just a flag for whether your company is already in our API network.

How We Grade a Company

  1. Discover. We work entirely from public sources, with no inside access and no telemetry. Starting at your domain, we probe the paths agents check (/.well-known/, /llms.txt, /openapi.json, and your docs, developer, and api subdomains), then follow what we find: harvesting llms.txt and the links it advertises, walking source repos when no spec sits at a standard path, and detecting surfaces like MCP servers, SDKs, and a CLI. We record how each asset was found, because discoverability is itself a signal.
  2. Verify. Not everything discovery turns up is real, reachable, or actually yours, so we verify before grading. We confirm each resource is reachable, verify the company published it rather than a third-party mirror or lookalike, de-duplicate by content, and group everything into the logical APIs it belongs to. Only verified, publisher-attributed surfaces make it into the grade.
  3. Grade. We then run 25 static checks across the five categories and all seven surfaces. Each is a concrete, verifiable probe (a parsed schema, a real network response, a fetched error body), not a survey or self-report. Because the model is surface-agnostic, a capability counts if any surface proves it (best-of, never worst-of), so an org strong on SDKs isn't penalized for lacking a spec. The result is a per-category breakdown of the exact gaps agents will hit.
API Ecosystem Report by Postman, Inc.
Tracking Cookies Used.
Privacy PolicyTerms of Service

Informational only. Provided "as is" without warranty, and not a rating or endorsement of any company. AI recommendations may be inaccurate.

© 2026 Postman, Inc.