An API Evangelist product

The API Evangelist Rating System

Sixteen years of API research by Kin Lane, distilled into a transparent, machine-readable rating every API provider can be measured by — composite quality, standalone agent readiness, and the full rubric that drives them.

APIs.io is the first company to license the API Evangelist Rating System

Every provider in the APIs.io catalog carries a composite score from 0 to 100 alongside a band label that summarizes how well the provider’s API surface is documented, governed, and made consumable for developers and agents.

The score is computed from machine-readable artifacts the provider has published — their apis.yml, their OpenAPI and AsyncAPI specifications, their documentation portal, their plans and rate-limit profiles, their MCP server, and so on. The rating is not a judgment of the provider’s commercial value or product quality — it is a measurement of how complete, transparent, and integration-ready the provider’s public API surface is.

Nothing here is subjective and nothing is hidden. Every one of the 74 checks below is listed with the points it awards and the facet it feeds, so any provider can work out precisely why they scored what they scored.

Rubric v0.4 · 6 bands · 6 facets · 74 checks · 332 points · updated 2026-07-17

Bands

The composite maps to one of 6 bands. Bands are how the rating shows up in search results and on provider pages.

Band cut points are calibrated against the catalog’s real distribution rather than picked round — the share column is what each band actually holds today.

Exemplar

70+

Reference-quality API operations across every facet — a rich contract, published governance, transparent operations, and machine-readable commercial terms. The top ~1% of the catalog, and the band no provider reaches by accident.

Strong

60 – 69.9

Solid contracts, transparent operations, and an easy start. Typically complete on four or five facets with one clear soft spot — most often governance or a missing commercial artifact.

Developing

45 – 59.9

Real signal across most facets with visible, nameable gaps. The contract exists but is thin on descriptions or examples, or the portal is good while governance and commercial terms are absent.

Thin

30 – 44.9

Limited machine-readable signal and partial portal coverage. Usually a provider with documentation a human can read but little a machine or agent can consume without scraping.

Emerging

15 – 29.9

More than an index entry, but the surface is still mostly links rather than artifacts. These providers have started publishing — a portal, a few common links, maybe a spec — and are the cohort most likely to move a full band from modest, well-targeted work.

Minimal

0 – 14.9

Index entry only; little beyond a description and a link. Nothing here is machine-readable enough for an agent to act on without a human first reading the site.

What changed in v0.4. The minimal band used to span the whole 0–29 range and held 40.7% of the catalog — a provider doing real work to climb from 6 to 28 never saw their label move, which defeats the point of scoring them at all. That range is not uniform: a large cohort sits at the very floor (an index entry and nothing else), and above it is a densely populated ramp. The emerging band now splits the two at the natural gap in the data. No provider's composite changed — this re-cut relabels, it does not rescore.

In addition to a band, providers carry a trending marker — rising, flat, or falling — from week-over-week change in composite. A delta of +5 or more marks rising; -5 or worse marks falling. Trending populates once at least two snapshots exist in the 12-week history window, and shows next to the band in search results.

The composite is a weighted blend of 6 facets. Each is scored independently from 0 to 100 against its own checks, then weighted in.

Facet	What it measures	Weight
Contract Quality	Technical depth and richness of the API contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD.	25%
Developer Ergonomics	How easy is it to get started? SDKs, CLI, portal, getting-started, documentation, sandbox/console, MCP server, and authentication clarity.	20%
Commercial Clarity	Are commercial terms machine-readable? Plans, pricing, sign-up, terms of service, privacy, finops mapping, compliance/trust.	20%
Operational Transparency	Does the provider expose how the API behaves operationally? Rate limits, status, change log, deprecation, security disclosure.	13%
Governance	Outcomes of Spectral linting and presence of governance artifacts (rulesets, vocabulary). Severity-weighted.	12%
Discoverability	Can the API be found and understood from machine-readable metadata alone? Driven by apis.yml completeness, tagging, and identity signals.	10%

A facet only counts what a provider could plausibly have. Checks that need an artifact the provider doesn't publish at all are scored N/A, not zero — they leave both the numerator and the denominator. A provider with no event-driven surface is not punished for having no AsyncAPI; they are simply scored on the contract they do publish. Where a provider has several specs of one kind, credit is proportional to how many pass, so one polished spec does not paper over ten thin ones.

The 74 Checks

Every check, grouped by the facet it feeds and the artifact it reads. Points are the maximum a check can award; the rule is the actual predicate the scorer evaluates.

Technical depth and richness of the API contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD.

OpenAPI

The HTTP contract itself. These checks parse every OpenAPI document the provider publishes, so they measure what the spec actually contains rather than whether one exists. A provider with several specs earns credit proportional to how many pass.

Check	Rule	Points
Publishes an OpenAPI spec At least one OpenAPI document exists. The largest single award in the rubric, because nearly every downstream capability — SDK generation, mocking, linting, agent tool-calling — is unlocked by having a contract at all.	`at least one api has spec_type == "OpenAPI"`	20
OpenAPI 3.1 Published against 3.1, which aligns with modern JSON Schema and supports webhooks natively. Scored above 3.0 rather than instead of it.	`openapi version is 3.1.x`	5
OpenAPI 3.0 Published against 3.0. Still widely tooled and a long way ahead of Swagger 2.0, but no longer where the specification is moving.	`openapi version is 3.0.x`	3
Complete info block Title, a description of real length, a version, and a contact. The metadata a consumer needs to identify and reach the API's owner.	`info has title, description (>= 50 chars), version, contact`	4
Real servers declared The spec points at a callable host. A localhost server fails — a contract you cannot call is documentation, not an interface.	`servers[] non-empty and not localhost`	3
Operations have summaries At least 80% of operations carry a summary. Summaries are what render in reference docs and what an agent reads to pick the right operation.	`>= 80% of operations have summary`	6
Operations have descriptions At least 80% of operations carry a description. The difference between knowing an operation's name and knowing what it does.	`>= 80% of operations have description`	6
Operations are tagged At least 80% of operations are tagged, which is what groups a reference into navigable sections instead of one flat list of endpoints.	`>= 80% of operations have tags`	4
Unique operationIds Every operation has a unique operationId. Required for clean SDK method names and stable agent tool names; duplicates silently break both.	`100% of operations have unique operationId`	4
Success responses defined Every operation documents at least one success response, so a consumer knows the shape of what they get back.	`every operation defines >= one 2xx response`	5
Error responses documented At least half of operations document a 4xx response schema. The most commonly skipped part of a contract, and the part integrators need most when things go wrong.	`>= 50% of operations define a 4xx response schema`	4
Examples present The spec carries at least one example. Examples are what make generated docs and mock servers immediately useful.	`at least one example present anywhere in spec`	4
Reusable components Five or more component schemas, actually referenced via $ref. Evidence the spec is modelled rather than copy-pasted per endpoint.	`components.schemas count >= 5 and used via $ref`	3
Security schemes defined The spec declares how authentication works, so a consumer can authenticate from the contract without hunting through prose docs.	`components.securitySchemes non-empty`	4
Security applied to operations Declared schemes are actually bound to operations, globally or individually. A scheme defined but never applied tells a consumer nothing about what a given call requires.	`security applied globally or per-operation`	3
Webhooks or callbacks The spec describes what the API sends back out, not only what it receives — the event surface most providers document only in prose, if at all.	`webhooks or callbacks defined (3.1) or callbacks (3.0)`	2

AsyncAPI

The event-driven contract. Only 213 AsyncAPI documents exist across the entire catalog, so these checks are N/A for most providers — a provider with no event surface is not penalized for the absence, and these points are excluded from their denominator entirely.

Check	Rule	Points
Publishes an AsyncAPI spec At least one AsyncAPI document exists, describing the messaging or streaming surface with the same rigor the OpenAPI applies to the request/response one.	`at least one api has spec_type == "AsyncAPI"`	12
AsyncAPI 3.x Published against 3.x, which separates channels from operations and is where the specification's tooling is consolidating.	`asyncapi version is 3.x`	4
Channels defined The spec declares the channels messages flow over — the event equivalent of declaring paths.	`channels[] non-empty`	4
Messages carry payload schemas At least 80% of messages reference a payload schema, so a subscriber knows the shape of what arrives rather than discovering it at runtime.	`>= 80% of messages reference a payload schema`	5
Protocol bindings on servers Servers declare their protocol bindings — Kafka, AMQP, WebSocket, MQTT — which is what makes the contract actually connectable.	`servers define protocol bindings`	3
Server security schemes At least one server declares how to authenticate against it.	`securitySchemes defined for at least one server`	3

JSON Schema

Schemas published as standalone, addressable artifacts rather than only inlined in a spec — reusable across specs, validators, and codegen.

Check	Rule	Points
Publishes JSON Schema At least one JSON Schema is published as its own artifact, so the data model can be validated against and reused independently of any single API.	`at least one api property has type == "JSONSchema"`	6
Schema per resource Two or more schemas, broken out per primary resource rather than one catch-all document — evidence the data model is decomposed.	`schemas extracted per primary resource (>= 2)`	4

JSON-LD

Semantic context — what the API's terms actually mean, linked to shared vocabularies. The thinnest-populated artifact in the catalog, and the one that most separates an API a machine can call from one a machine can reason about.

Check	Rule	Points
Publishes a JSON-LD context At least one JSON-LD context is defined, binding the API's terms to shared semantics instead of leaving field names to be guessed from spelling.	`at least one jsonld context defined`	5
Context defines classes Five or more classes in a context — a modelled domain rather than a token gesture at semantics.	`any jsonld context has class_count >= 5`	3
Context defines properties Ten or more properties, giving the classes enough detail to be useful to a consumer mapping the API onto their own model.	`any jsonld context has property_count >= 10`	3

How easy is it to get started? SDKs, CLI, portal, getting-started, documentation, sandbox/console, MCP server, and authentication clarity.

Developer Ergonomics

How far is a newcomer from their first successful call? These checks track the on-ramp — portal, quickstart, auth docs, SDKs, sandbox — plus the newer agent-facing entry points (MCP servers and Agent Skills) that increasingly serve the same purpose for a non-human consumer.

Check	Rule	Points
Developer portal A dedicated developer portal — one front door, rather than API information scattered through a marketing site.	`common[].type includes "DeveloperPortal" (alias-aware)`	4
Documentation Narrative documentation explaining how the API works and how to use it.	`common[].type includes "Documentation"`	4
API reference A complete endpoint-level reference — distinct from narrative docs, and what a developer returns to after their first call.	`common[].type includes "APIReference" (alias-aware)`	3
Getting started guide An explicit quickstart. The artifact most correlated with a developer reaching a first successful call, which is why it outscores the reference itself.	`common[].type includes "GettingStarted" or "Quickstart"`	5
Authentication documented Authentication is documented as its own topic. Auth is where most integrations stall, and burying it inside a general guide is where most developers give up.	`common[].type includes "Authentication"`	5
At least one SDK At least one client library, so a consumer is not writing HTTP plumbing before writing anything of their own.	`count(common[].type == "SDK" alias-aware) >= 1`	3
Three or more SDKs Three or more languages covered — evidence of investment in a real developer audience rather than one favored stack. Awarded on top of the first SDK.	`count(common[].type == "SDK" alias-aware) >= 3`	4
Command-line interface A CLI, which is how the API gets used in scripts, CI, and exploration.	`common[].type includes "CLI"`	3
Console or sandbox Somewhere to try the API without wiring up credentials and a project first.	`common[].type includes "Console" or "Sandbox" or "Playground"`	3
Postman collection A runnable collection — the fastest path from reading about the API to calling it.	`common[].type includes "Postman" (alias-aware)`	2
MCP server A Model Context Protocol server, making the API directly callable by agents. Weighted alongside the strongest human on-ramps because it increasingly is one.	`common[].type includes "MCPServer"`	4
Agent Skill A published Agent Skill — packaged instructions for an agent to use the API correctly, rather than leaving it to infer usage from the spec.	`common[].type includes "AgentSkill"`	3
Support channel A route to a human or a community when the documentation runs out.	`common[].type includes "Support" or "HelpCenter" or "Community"`	2
Blog A blog. The lightest signal in the rubric, but a live one — it shows the API is still being talked about by the people who build it.	`common[].type includes "Blog"`	1

Are commercial terms machine-readable? Plans, pricing, sign-up, terms of service, privacy, finops mapping, compliance/trust.

Commercial Clarity

Can a team evaluate, adopt, and pay for this API without booking a sales call? This facet measures whether the commercial surface is as machine-readable as the technical one — the questions procurement and legal ask, answered in public.

Check	Rule	Points
Plans published Access plans exist as structured, machine-readable data rather than a pricing page a human has to interpret. The heaviest award in this facet.	`plans[0].plan_count >= 1`	8
Multiple plans Three or more plans, describing a real tiering model — typically a free or trial tier through to production volume.	`plans[0].plan_count >= 3`	4
Pricing published Pricing is public. "Contact us" is an answer, but it is not this one.	`common[].type includes "Pricing"`	4
Self-service sign-up A developer can get credentials themselves. Self-service sign-up is the line between an API you can try this afternoon and one you can try next quarter.	`common[].type includes "SignUp" or "Login"`	5
Terms of service Published terms — what a consumer is actually agreeing to when they call the API.	`common[].type includes "TermsOfService" (alias-aware)`	4
Privacy policy A published privacy policy covering what happens to data passing through the API.	`common[].type includes "PrivacyPolicy" (alias-aware)`	4
FinOps mapping Cost is mapped to usage in a machine-readable way, so consumption can be modelled and attributed rather than discovered on an invoice.	`len(finops) >= 1`	3
Compliance published Certifications and compliance posture are stated in public — SOC 2, ISO, HIPAA, GDPR — where a reviewer can find them without asking.	`common[].type includes "Compliance"`	3
Trust center A trust center consolidating security, compliance, and privacy posture into one place built for the person evaluating whether to depend on you.	`common[].type includes "TrustCenter" or "Trust"`	3

Does the provider expose how the API behaves operationally? Rate limits, status, change log, deprecation, security disclosure.

Operational Transparency

Does the provider expose how the API behaves in production — what it limits, when it breaks, what changed, and what is going away? These are the artifacts a team needs to depend on an API, as opposed to merely call it.

Check	Rule	Points
Change log A published change log. The single most useful operational artifact: it lets a consumer see what moved without diffing the spec themselves.	`common[].type includes "ChangeLog" (alias-aware)`	6
Status page A status page exists, so an integrator debugging a failure can tell "the API is down" from "my code is broken" without filing a ticket.	`common[].type includes "StatusPage"`	6
Rate limits documented Rate limits are published as machine-readable data. The heaviest award in this facet — undocumented limits are the most common cause of an integration that works in development and fails under load.	`rate_limits[0].limit_count >= 1`	8
Rate limits detailed Three or more distinct limits, reflecting how the API actually tiers and throttles rather than a single blanket number.	`rate_limits[0].limit_count >= 3`	4
Deprecation policy A stated deprecation policy — how much notice a consumer gets before something they depend on is removed.	`common[].type includes "Deprecation" (alias-aware)`	3
Security disclosure A route for reporting vulnerabilities. Its absence tells a security researcher to go public instead.	`common[].type includes "Security" (alias-aware)`	4
Webhooks advertised The provider advertises a webhook surface, so consumers can react to events rather than poll for them.	`common[].type includes "Webhooks"`	3
GitHub organization A public GitHub organization — where SDKs, specs, and issues live in the open.	`common[].type includes "GitHubOrganization" (alias-aware)`	2
Public roadmap A public roadmap, letting consumers plan against where the API is going rather than only where it is.	`common[].type includes "RoadMap" or "Roadmap"`	2

Outcomes of Spectral linting and presence of governance artifacts (rulesets, vocabulary). Severity-weighted.

Spectral Rules

Published governance — the rules a provider holds their own API to, and the outcome of running them. This facet rewards publishing a ruleset AND passing it; a large ruleset that throws errors on the provider's own spec scores below a modest one that passes clean.

Check	Rule	Points
Publishes a ruleset A Spectral ruleset exists. The provider has written down what "good" means for their API surface instead of leaving it to reviewer taste.	`rules[0].rule_count >= 1`	10
Substantial ruleset Twenty or more rules — a ruleset with real coverage rather than the handful that ship in a starter template.	`rules[0].rule_count >= 20`	5
Low error density No more than 20% of rules fire at error severity against the provider's own specs. Measures whether governance is actually being met, not just declared.	`severity_counts.error / rule_count <= 0.20`	10
Clean lint The provider's specs pass their own ruleset with zero errors. Awarded on top of low error density.	`severity_counts.error == 0`	5
Balanced severities The ruleset uses warn and info, not only error. A ruleset where everything is an error cannot express guidance — only refusal.	`warn and info both > 0`	3
Publishes a vocabulary A controlled vocabulary is published, so the provider's naming is a documented decision rather than an accident of whoever wrote each endpoint.	`common[].type includes "Vocabulary"`	5

Can the API be found and understood from machine-readable metadata alone? Driven by apis.yml completeness, tagging, and identity signals.

apis.yml

The provider's APIs.json index — the root document that makes everything else findable. Every other artifact in this rubric is discovered through it.

Check	Rule	Points
Publishes an apis.yml index The provider maintains a real APIs.json index rather than being catalogued from the outside. The single highest-value discoverability signal: it is the difference between a provider describing itself and being described.	`source_filename == "apis.yml"`	10
Substantive description At least 200 characters of description. Enough for a human or an agent to decide whether the API is relevant without opening the site.	`len(description) >= 200`	5
Tagged for discovery Five or more tags. Tags are how the API surfaces in topical search and how it gets placed into industries and areas rather than sitting unclassified.	`len(tags) >= 5`	5
Provider image A logo or image is referenced, so the provider renders as a recognizable card in search results and listings instead of a bare line of text.	`image is set`	2
Named maintainer A contactable maintainer email. Establishes that someone owns the index and gives consumers a route to reach them.	`maintainers[0].email is set`	3
Created and modified dates Both timestamps present as ISO dates, so freshness is machine-readable and a consumer can tell a maintained index from an abandoned one.	`created and modified both ISO dates`	2
Indexes three or more APIs The index covers a real surface rather than a single endpoint — evidence the provider is cataloguing their whole platform.	`api_count >= 3`	3
Human URL on every API Each indexed API points at documentation a person can read. Without it, an entry is a name with nowhere to go.	`every api has humanURL`	5
Base URL on every API Each indexed API declares a real, callable base URL. A localhost base URL fails this check — it signals a spec that was published without ever being pointed at production.	`every api has baseURL and no baseURL contains "localhost"`	5

Agent Readiness separate score

Every provider also carries an Agent Readiness score from 0 to 100 — shown next to the composite on the provider page and in search. It answers a different question from the composite: not how complete is this API for a developer, but how safely can an autonomous AI agent drive it.

A human developer papers over a lot of friction — ambiguous errors, undocumented idempotency, prose-only auth, HTML changelogs. An agent cannot. Every implicit convention a human silently absorbs is a place an agent retries blindly, double-charges a card, or hallucinates a payload. Agent readiness measures whether those conventions have been replaced with machine-readable signals. The model is adapted from api-evangelist/agent-readiness.

Why it is separate. Agent readiness and the composite are correlated but not the same — a provider can be Thin on the composite yet Agent-Ready because it ships a machine-readable access contract, or Strong for humans yet Human-Only for agents because its errors are free text and its retries are unsafe. Merging them into one number would hide exactly the gap this score exists to expose, so it is scored and displayed on its own axis. It is not blended into the composite.

Agent Readiness Bands

Agent-Native

60+

Built to be driven by agents — the baseline contract plus the differentiators most providers lack: an MCP server, idempotency, stable error semantics, examples. The providers an agent can drive safely today.

Agent-Ready

45+

An agent can drive the core surface. A machine-readable contract, an agentic-access classification, and documented auth are in place; the safety rails (idempotency, stable errors, rate-limit signalling) mostly are not.

Agent-Aware

15+

Partial machine-readable surface. An agent can read some of the API but would hit implicit conventions a human silently absorbs — the gaps where it retries blindly or gets stuck.

Human-Only

Little an agent can consume without a human first reading the site. A developer can integrate it; their agent cannot yet.

The 12 Dimensions

Each dimension is a provider-level signal, scored present/absent, awarding the points shown. The earned total is normalized to 0–100 (104 points possible) and mapped to a band. Unlike the composite, a missing contract here is a real deficiency, not N/A — an API with no machine-readable surface cannot be driven by an agent at all, so every dimension is always counted.

Dimension	Signal	Points
Machine-Readable Contract A public OpenAPI contract exists. Agents call APIs from contracts, not HTML docs — with no spec there is no programmatic surface to drive, which is why this is the single largest award.	`api_specs includes an OpenAPI document`	18
Agentic Access Contract The provider publishes an x-agentic-access contract classifying each operation by action-class, consequence, and human-in-the-loop escalation. The most explicit "this API was designed to be driven by an agent" signal in the catalog.	`agentic_access artifact present (x-agentic-access), or common[].type AgenticAccess`	15
MCP Server A Model Context Protocol server makes the API directly callable by agents over a uniform tool surface — the most direct expression of agent-first design.	`common[].type includes MCPServer`	12
Machine-Readable Auth The authentication model is documented in a form an agent can negotiate without reading prose — OIDC discovery, declared scopes, or OpenAPI security schemes.	`common[].type includes Authentication, OpenIDConnect, OAuthScopes, or API Keys`	10
Idempotency Mutating operations accept an idempotency key. Agents retry; without idempotency a retry double-charges a card, sends a message twice, or opens a duplicate ticket.	`common[].type matches /idempoten/i`	9
Stable Error Semantics Errors are a documented, stable envelope with stable codes. Agents branch on errors — free-text messages break that branching and send an agent into blind retries.	`common[].type includes ErrorCatalog, ErrorCodes, or DeclineCodes`	8
Request/Response Examples Meaningful examples are published. Examples are the cheapest way an agent learns a payload shape before it ever makes a call.	`common[].type includes Examples or Code Samples`	7
Rate-Limit Signaling Rate-limit behaviour is documented as machine-readable data. An agent needs to know when to back off; "you will get a 429 eventually" is not something it can plan against.	`common[].type includes RateLimits, or a rate_limits artifact is present`	7
Typed Event Surface Event and webhook surfaces are described by a contract, so an agent that must react to state changes has a typed surface rather than example payloads.	`api_specs includes AsyncAPI, or common[].type includes Webhooks`	6
Agent Skills Packaged operating instructions an agent should follow when using the API, rather than leaving usage to be inferred from the spec.	`skills artifact present, or common[].type includes AgentSkill`	5
Well-Known Catalog A /.well-known/api-catalog (RFC 9727) linkset — the canonical machine entrypoint an agent hits first to discover the provider's APIs and MCP endpoints.	`common[].type includes WellKnown, APICatalog, or api-catalog`	4
Consent & Bot Identity Forward-looking signals for machine-readable AI usage preferences (AIPREF, Content-Signals) and cryptographically identified agent traffic (Web Bot Auth / RFC 9421). Rare today; rewards the providers defining the frontier.	`common[].type includes AIPREF, ContentSignal, WebBotAuth, HTTPMessageSignatures, or SecurityTxt`	3

Sourced from what the catalog already knows. Every dimension above reads a signal already published — the x-agentic-access contract, an MCP server, Agent Skills, idempotency and error-catalog links, a well-known catalog. Nothing there requires the provider to do new work beyond making an existing practice discoverable, and the score re-runs on every scoring pass.

Planned — deeper, spec-level checks

The 12 dimensions above are scored from provider-level signals — a published link or artifact that says a practice exists. The dimensions below go one level deeper: they parse each OpenAPI operation to verify the practice is actually in the contract an agent will drive, not just asserted in a doc. They are on the roadmap and not yet scored — listed here so the model is complete and the gap between “detected from a link” and “verified in the spec” is explicit. When they ship, they move into the table above with points, and the bands recalibrate.

Planned dimension	What it will verify	Status
Idempotency Key (verified in spec) Today idempotency is credited from a provider-level link (an "Idempotent Requests" doc). The deeper check parses each OpenAPI and confirms POST/PATCH operations actually declare an Idempotency-Key header — the difference between a provider saying they support it and the contract an agent can act on. Deepens the provider-level `idempotency` signal.	`OpenAPI: mutating operations declare an Idempotency-Key header parameter`	planned
Rate-Limit Response Headers Today rate limits are credited from documented limits. The deeper check confirms the API surfaces live rate-limit state in response headers (X-RateLimit-Limit/Remaining/Reset), which is what an agent reads to know when to back off mid-run rather than after a 429. Deepens the provider-level `rate_limit_signal` signal.	`OpenAPI: responses document X-RateLimit-* (or RateLimit) headers`	planned
Stable Error Envelope Today error semantics are credited from an error-catalog link. The deeper check confirms a single error schema is referenced across error responses — a stable, typed envelope an agent can branch on, not just documented codes. Deepens the provider-level `error_semantics` signal.	`OpenAPI: a shared error schema is $ref-ed across 4xx/5xx responses`	planned
Dry-Run / Simulate Mode No provider-level proxy exists for this one. The check parses each OpenAPI for a dry-run or simulate parameter on destructive operations, letting an agent plan an action before it commits — the safest agent-native affordance, and the rarest.	`OpenAPI: destructive operations expose a dry_run/simulate parameter`	planned

How a Score is Computed

The rubric lives at signals/_data/scoring.yml and is the single source of truth. The copy this page renders is mirrored from it on every build, so what you read here is what the scorer runs.

Per-artifact checks. Each check has an id, a facet, a points value, and a rule — the predicate the scorer evaluates. “every api has humanURL” awards 5 points toward Discoverability. 74 checks run today across apis.yml, OpenAPI, AsyncAPI, JSON Schema, JSON-LD, Spectral rulesets, operational links, developer-experience artifacts, and commercial artifacts.
Facet sub-score. A facet’s raw score is the sum of its awarded points, normalized against the points that were actually applicable to that provider, to yield 0–100. Applicability matters: N/A checks leave the denominator entirely.
Composite. The 6 sub-scores are blended using the weights above.
Band. The composite maps to one of the 6 bands.
Trending. If a prior snapshot exists in the 12-week window, the score is compared against the most recent one and a rising / flat / falling label is attached.

Scores are recomputed against the latest catalog state on every scoring run. The current score, band, scored-at date, and rubric version are written into each provider’s front matter and shown at the top of every provider page.

Contracts are read, not merely counted. Contract Quality parses every OpenAPI and AsyncAPI document a provider publishes — 74 checks include operation-level summary and description coverage, unique operationIds, 2xx and 4xx response schemas, component reuse via $ref, and whether declared security schemes are actually applied. A provider is scored on what their contract contains, not on whether one exists.

How to Improve Your Rating

Every area of the rating can be raised, and none of it is a mystery. The composite is a blend of six facets, the agent-readiness score is a set of 12 dimensions, and every check that feeds them is published above with the exact points it awards. There is no hidden component and no number you cannot move by publishing an artifact.

See exactly where your points are. On any provider page, click the band next to the score. It opens a full breakdown of that provider’s rating — a diagram of all six facets plus agent readiness, then every metric itemized with the points applied (green) versus possible (red), so you can see at a glance which artifacts are earning points and which are leaving them on the table. The cheapest wins are almost always things that are already true but simply undeclared — a status page, a change log, a rate-limit profile, an idempotency doc that exists on your site but appears nowhere machine-readable.

The rating is computed from your API Evangelist repository

Every provider in the catalog is profiled from a public repository in the API Evangelist GitHub organization — github.com/api-evangelist/<your-provider>. That repository is where the apis.yml index, the OpenAPI and AsyncAPI specs, the plans, the rate limits, the agentic-access contract, and every other scored artifact live. Because it is open, improving your rating is a normal open-source contribution:

Ask a question — open an issue. Not sure why a check is failing, or which artifact would move a facet? Open an issue on your provider’s repository and I will answer it there.
Add an artifact — submit a pull request. Publish the missing spec, plans, rate-limit profile, or agentic-access contract as a pull request against your repository. Once it is merged, the next scoring run picks it up and your score moves — no gatekeeping, no fee.
Have it done for you — prioritized profiling. If you would rather not do the work yourself, API Evangelist offers prioritized profiling for $2,500: I audit your public API surface against the full rubric, add the machine-readable artifacts to your repository, and get your provider profiled ahead of the regular cadence. See Prioritized API Rating & Profiling.

The first two paths are free and always will be — the rubric is open specifically so any provider can climb it on their own. The third is simply the fast lane for teams that want the work done for them.

What the Rating is For

The rating is meant to be useful in two directions:

For developers and agents picking providers. A strong or exemplar pill in a search result signals that the provider has invested in making the API genuinely consumable — readable contracts, predictable operations, transparent commercials. Search on APIs.io blends the composite into result ranking, so well-rated providers float up among relevance-matched results, and you can filter results down to a single band.
For providers improving their API surface. The rubric is open and every check is published above with its exact points and predicate. A provider’s score header names their band and composite; this page names everything that could move it. The cheapest wins are usually the artifacts that are already true but simply undeclared — a status page, a change log, a rate-limit profile that exists on the site but appears nowhere machine-readable.

What the Rating is Not

Not a quality judgment of the provider’s product. A great product can ship thin API documentation; a mediocre one can ship exemplary documentation. This measures the contract and documentation surface, not the product behind it.
Not a security audit. Operational Transparency notes whether a security disclosure route exists. It does not assess security posture.
Not a compliance certification. Commercial Clarity looks for the presence of ToS, privacy, compliance, and FinOps signals. It certifies no regulatory standard.
Not a measure of popularity. Nothing here counts traffic, customers, or revenue.
Not stable across rubric versions. Each schema_version reflects a snapshot of what was measured. The rubric evolves deliberately as new artifact types — MCP servers, Agent Skills, llms.txt manifests — become standard. Compare providers within a version, not across them.

Source

Rubric: signals/_data/scoring.yml — mirrored into this site on every build; the source of truth for what counts and how much.
Scorer: signals/score.rb — the source of truth for evaluation. Reads the rubric, parses every published spec, writes the score block into each provider’s front matter.
History snapshots: signals/_data/history/<date>.json — one row per provider per scoring run, retained 12 weeks for trend calculation.
Current version: schema v0.4 · last updated 2026-07-17 · maintainer kin@apievangelist.com

If you maintain a provider profile and want to know what is pulling your score up or down, the score header on your provider page names your band and composite, and the checks above name everything that feeds it. Pull requests against the upstream api-evangelist provider repo flow into the next scoring run.