I have spent my whole career forming opinions about whether an API is any good — not whether the company is valuable or the product is clever, but the narrower, more useful question of whether I can find it, understand it, trust how it behaves, and integrate it without a human beside me filling in what the documentation left out. I made that judgment thousands of times in my head before I finally wrote it down. The result is the API Evangelist Rating System: a transparent, machine-readable rubric that scores a provider's public API surface so the judgment scales, travels, and can be argued with by anyone.

Every input is an artifact the provider actually publishes — an OpenAPI contract with real descriptions and error responses, a change log, documented rate limits, plans a buyer can read without a sales call. There is no panel, no vibes, and no pay-to-play tier that buys a better number. The whole rubric is out in the open, so any provider can see exactly why they scored what they scored and precisely what would move them up.

Two scores, on purpose

Composite quality is what people expect: how complete, transparent, and integration-ready an API is for a human developer — a weighted blend of six facets and 74 individual checks, deliberately blunt because the point is comparability, not a certificate.

Agent readiness is scored separately, because a human developer papers over an enormous amount of API friction that an autonomous agent cannot. Every implicit convention a human silently absorbs — ambiguous errors, undocumented idempotency, prose-only auth — is a place an agent retries blindly, double-charges a card, or hallucinates a payload. It lives on its own axis because a provider can be thin for humans yet ready for agents, or strong for humans yet useless to their agents.

Composite quality bands

A provider's composite score (0–100) maps to one of six bands, calibrated against the real distribution of the catalog rather than picked round. The share column is what each band actually holds today.

Exemplar	70+ 0.6%	Reference-quality API operations across every facet — a rich contract, published governance, transparent operations, and machine-readable commercial terms. The band no provider reaches by accident.
Strong	60–69.9 6.4%	Solid contracts, transparent operations, and an easy start. Complete on four or five facets with one clear soft spot.
Developing	45–59.9 22.3%	Real signal across most facets with visible, nameable gaps — a thin contract, or a good portal with no governance.
Thin	30–44.9 30.0%	Limited machine-readable signal — documentation a human can read but little a machine or agent can consume without scraping.
Emerging	15–29.9 24.9%	More than an index entry but still mostly links rather than artifacts — the cohort most likely to move a full band from modest, well-targeted work.
Minimal	0–14.9 15.8%	Index entry only; little beyond a description and a link.

The six facets

The composite is a weighted blend of six facets, each scored 0–100 from its own checks. The weights decide what "good" means.

Facet	What it measures	Weight
Contract Quality	Technical depth of the contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD.	25%
Developer Ergonomics	How fast is a first call? SDKs, CLI, portal, getting-started, docs, sandbox, MCP server, auth clarity.	20%
Commercial Clarity	Are commercial terms machine-readable? Plans, pricing, sign-up, ToS, privacy, FinOps, compliance.	20%
Operational Transparency	How the API behaves in production — rate limits, status, change log, deprecation, security disclosure.	13%
Governance	Outcomes of Spectral linting and published governance artifacts (rulesets, vocabulary), severity-weighted.	12%
Discoverability	Can the API be found from machine-readable metadata alone? apis.yml completeness, tagging, identity.	10%

Agent readiness separate score

A standalone 0–100 score measuring how safely an autonomous agent can drive the API, mapped to its own four bands. A provider can be Thin for humans yet Agent-Ready, or Strong yet Human-Only.

Agent-Native	60+ 1.4%	Built to be driven by agents — the baseline contract plus the differentiators most lack: MCP, idempotency, stable errors, examples.
Agent-Ready	45+ 43.3%	An agent can drive the core surface. Contract, agentic-access classification, and auth are in place; the safety rails mostly are not.
Agent-Aware	15+ 16.4%	Partial machine-readable surface. An agent can read some of the API but hits implicit conventions and gets stuck.
Human-Only	0+ 38.9%	Little an agent can consume without a human first reading the site.

Twelve dimensions feed the score (points each):

Machine-Readable Contract 18Agentic Access Contract 15MCP Server 12Machine-Readable Auth 10Idempotency 9Stable Error Semantics 8Request/Response Examples 7Rate-Limit Signaling 7Typed Event Surface 6Agent Skills 5Well-Known Catalog 4Consent & Bot Identity 3

Transparency is the product

The rubric is versioned, all 74 checks are enumerated with the points they award, and the bands are calibrated against the real distribution of what is actually out there rather than picked to flatter anyone. If you disagree with a weight, you can see the weight. If you think a check is wrong, you can see the check. A rating nobody can inspect is just an opinion with better production values, and the industry has enough of those.

Where it runs

The rating system is licensable, and APIs.io is the first company to license it. It runs across the entire APIs.io catalog on every rebuild, shows up in search results and on every provider's page, and is served through the APIs.io API and MCP server so both people and their agents can filter and rank by it.

See it running on APIs.io

Browse live ratings for thousands of API providers, and read the full rubric — every facet, all 74 checks, both scoring axes, and the agent-readiness dimensions with their exact points.

The full rubric & live ratings at APIs.io →

How a provider improves

Every provider is profiled from a public repository in the API Evangelist GitHub organization — github.com/api-evangelist/<provider>. That is where the scored artifacts live, so improving a rating is a normal open-source contribution:

Ask a question — open an issue on the provider's repository.
Add an artifact — submit a pull request with the missing spec, plans, rate limits, or agentic-access contract; the next scoring run picks it up.
Have it done for you — prioritized profiling for $2,500: I audit your surface, add the artifacts, and move you up the queue.

The first two paths are free and always will be — the rubric is open specifically so any provider can climb it on their own.

{{ page.title }}