The API Evangelist rating system

Kin Score

Sixteen years of Kin Lane studying the technology, business, and politics of APIs — that opinionated judgment distilled into a transparent, machine-readable rating every API provider can be measured by. Composite quality, agent readiness, and the full rubric that drives them, all under one score.

APIs.io is the first company to license Kin Score

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 106 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.9.1 · 6 bands · 7 facets · 106 checks · 517 points · updated 2026-08-04

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

66+

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

56 – 65.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

42 – 55.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

28 – 41.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

13 – 27.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 – 12.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.9.1. Both band sets were re-cut — the composite from 70/60/45/30/15 to 66/56/42/28/13, agent readiness from 56/42/14 to 46/34/6. v0.6 is a correctness release rather than a change in ambition, so the cuts moved with the scores: the batch shifted the composite down by a mean of 1.92 points, and the re-cut deliberately preserves what each rung means (Exemplar held 1.1% of the catalog before and 1.0% after; Strong 3.8% and 4.1%). 2,239 providers change band — 8.8%, against 13.8% had the old cuts been left in place, and every one of them moved because its evidence changed rather than because the ladder did.

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 7 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 106 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 a machine-readable contract At least one machine-readable contract exists, in ANY format the ecosystem actually uses. 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.CONTRACT-TYPE-AGNOSTIC IN 0.6, and renamed from `openapi_present` to say so. Through 0.5.1 this check read OpenAPI and AsyncAPI only, which meant entire FHIR-native, GraphQL-native and EDI-native markets were recorded as having no contract for a format the rubric simply declined to read. Epic served a 59-resource FHIR R4 CapabilityStatement — plus STU3, DSTU2 and a smart-configuration — and read `spec_presence: false`, `contract_quality: 22.6`. That was a measurement artifact, not a judgment about Epic.PROVENANCE-GRADED IN 0.6. An API-Evangelist-modeled spec credits at 0.25. A provider-served contract you can download should outrank one written on the provider's behalf, and until 0.6 they were indistinguishable.	`at least one OpenAPI, AsyncAPI, GraphQL SDL or FHIR CapabilityStatement`	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
Servers resolve to a real host NEW IN 0.6. A specification can be genuinely provider-published, verbatim, and still be uncallable. Every CAMARA server declaration in the entire telecom stack is the template variable `{apiRoot}` and every openIdConnectUrl is a CAMARA placeholder pointing at example.com — across 19 standards and exposure repositories there was exactly one absolute base URL. Insurance produced the same defect from the other direction: Majesco declares api.majesco.example.com and ACORD api.insurer-internal.example.com. The rubric scored all of it as full contract quality.Graded on the SHARE of a provider's specs that carry a resolvable host, so a provider with one placeholder spec among twenty is not treated like one whose entire surface is uncallable. Catalog-wide at 0.6: 10,950 of 87,612 specs are uncallable as published, and 834 providers hold no spec with a resolvable host at all.The distinction that took care to get right: a TEMPLATED host that still carries a real domain — `https://{region}.api.acme.com`, or Yardi's `https://{server}.yardi.com/{clientUrl}/webservices` — passes. A consumer with the variable filled in reaches a host that exists. Only a host that is nothing but substitution variables, or a known placeholder domain, fails. A naive "contains a brace" test would have failed a large share of perfectly callable multi-region specs, and a naive full-text grep for example.com over the catalog returned 4,320 false positives, because real specs mention example.com in their EXAMPLES. This check parses the `servers` block specifically.	`share of specs whose servers[].url carries a registrable domain, not a placeholder host or a bare template variable`	5
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 GRADED IN 0.6, previously a bit. As a boolean this check fired on a single token example anywhere in the document, which meant it ran near-universally across payments and healthcare and carried almost no information. It now grades on the SHARE of operations that actually carry a request or response example, so a provider who documents every operation outscores one who documented a single one. Examples are the cheapest way an agent learns a payload shape before it ever makes a call, and "the spec contains the string example:" was never evidence of that.	`share of operations carrying a request or response example`	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
Declares no deprecated OAuth grant NEW IN 0.7. The implicit grant returns an access token in the browser redirect fragment; the password grant has the client handle the user's credentials directly. Both are recommended against by the OAuth 2.0 Security BCP (RFC 9700) and removed outright in OAuth 2.1. Measured across 14,195 published contracts, 775 still declare implicit and 72 declare password - 28.9% of every OAuth-using contract. Vacuously satisfied by a contract declaring no OAuth: this scores the PRESENCE of a deprecated flow, not the absence of OAuth.	`no securityScheme declares the implicit or resource-owner-password OAuth grant`	4
Keeps credentials out of the query string NEW IN 0.7. An API key in the query string lands in server logs, proxy logs, browser history and referrer headers. 815 of 14,195 published contracts place the credential there. Vacuously satisfied where no apiKey scheme is declared.	`no apiKey securityScheme declares in: query`	3
Enumerates OAuth scopes NEW IN 0.7. Scope is how OAuth expresses least privilege - the difference between a token that can read a calendar and one that can delete an account. Only 15.3% of published contracts enumerate any scope, so roughly four in five OAuth-declaring contracts describe how to obtain a credential and never what it permits. This is the mechanism behind the missing least-privilege models found in every market report. Distinct from reg_oauth_scopes, which applies only where a regulatory regime does; this one applies to every provider. Vacuously satisfied without OAuth.	`every declared oauth2 flow enumerates at least one scope`	4
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

GraphQL

The GraphQL schema definition. A published SDL is a machine-readable contract in exactly the sense the contract facet means: introspectable, codegen-ready, and sufficient for an agent to construct a valid query without reading prose.

Check	Rule	Points
Publishes a GraphQL schema A schema definition file is published rather than only an interactive playground. An endpoint with introspection disabled and no published SDL is, to a consumer building against it, an undocumented API.	`a .graphql / .gql SDL is published`	10
Schema defines a real type system Twenty or more type definitions — a modelled domain rather than a handful of wrapper types around a REST passthrough.	`SDL declares >= 20 type definitions`	5
Schema is documented Half or more of the declared types carry description strings. In GraphQL the docstring IS the reference documentation — it is what renders in every explorer and what an agent reads to pick a field.	`>= 50% of type definitions carry a description string`	4

FHIR

The FHIR conformance surface — a CapabilityStatement declaring the resources, interactions, search parameters and profiles a server actually supports.

Check	Rule	Points
Publishes a FHIR CapabilityStatement The server publishes its conformance statement. This is the FHIR equivalent of shipping an OpenAPI, and it is served at a well-known path by every conformant server, which makes its absence a deliberate omission rather than an oversight.	`a CapabilityStatement / Conformance resource is published`	12
Broad resource coverage Twenty or more resources declared — the difference between a server that supports Patient and Observation and one that supports a working clinical record.	`CapabilityStatement declares >= 20 resources`	6

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.PROVENANCE-GRADED IN 0.6, and this is where the defect was worst. 1,882 of the 3,046 MCP artifacts in the catalog are API-Evangelist-derived CANDIDATES with `status: candidate` and `url: null` — 1,679 of them listed as an MCPServer in the provider's index, earning full credit for a server that does not exist. 8x8's own artifact states that its 312-tool catalog "is a proposal, not an 8x8 product." A derived candidate keeps a floor because it is a real, groundable artifact one adapter away from working; it can no longer outrank a running server.	`common[].type includes "MCPServer", graded by whether the provider runs it`	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.PROVENANCE-GRADED IN 0.6: 2,018 of 2,274 skill sets in the catalog were generated by API Evangelist from the provider's own specs. Provider-published agent skills exist, but they are rare — across the whole telecom sector, three.	`common[].type includes "AgentSkill", graded by who authored it`	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
Declared conformance profile The provider declares which standards it conforms to — FHIR, FAPI, PCI, ISO 20022, CAMARA — as a machine-readable artifact resolving against the standards catalog, rather than as a logo on a marketing page.PROVENANCE-GRADED, and the grading is the whole point. Half the conformance artifacts in the catalog (1,881 of 3,784) are API-Evangelist-derived readings of a provider's specs, not claims the provider made. Only a first-party declaration earns full credit here.THE BOUNDARY THIS CHECK HOLDS: adopting someone else's standard is not governance. Telecom is full of organizations that joined CAMARA, TM Forum or GSMA Open Gateway and govern nothing; governance is what you do to yourself. This credits evidence of INTERNALIZATION — a declared profile, an overlay, a published lint posture — never bare membership in a programme.	`a conformance/ artifact declares conformance to named standards`	6
Publishes an OpenAPI Overlay An OpenAPI Overlay — the provider expressing a repeatable, versioned transformation of its own contract rather than hand-editing it. Evidence of a spec pipeline, which is what governance looks like in practice.	`overlays/ contains an OpenAPI Overlay document`	4

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
Serves a .well-known surface The provider serves machine entrypoints at RFC 8615 well-known paths — an api-catalog linkset (RFC 9727), a security.txt, an OAuth protected-resource document. This is the address an agent tries FIRST, before it has read anything, and it is the discoverability signal a marketing site cannot fake.	`well-known/ carries an api-catalog, security.txt, or a protected-resource doc`	6
Publishes llms.txt An llms.txt — the provider stating, in a machine-readable file at a conventional path, what a language model should read to understand the product. Young, unratified, and adopted by 6,012 providers in this catalog, which makes it the fastest-moving machine-discoverability signal there is.	`llms/ carries an llms.txt`	4
Self-hosts the APIs.json index The provider serves its own APIs.json index from its own domain rather than being catalogued from the outside. `apis_yml_present` above rewards the index existing; this rewards the provider OWNING it — the difference between describing yourself and being described.	`apis.yml url points at a host the provider controls, not the catalog`	4

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

46+

Built to be driven by agents, and the provider built it — a contract, a real agent surface the provider itself publishes, and the safety rails the band gate now requires: idempotency AND a stable error envelope. The providers an agent can drive safely today, as opposed to the providers somebody has written agent artifacts about.

Agent-Ready

34+

An agent can drive the core surface. A machine-readable contract and documented auth are in place, and there is real agent-facing work beyond the baseline; the safety rails (idempotency, stable errors, rate-limit signalling) mostly are not.NARROWED IN 0.6. This band used to hold the enrichment baseline plateau — ~3,300 providers whose agentic-access contract was generated for them. Once that credit was graded down the plateau fell to 30–32 and the cut moved above it, so this band now means an agent surface the provider had a hand in rather than one the catalog supplied.

Agent-Aware

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 14 Dimensions

Each dimension is a provider-level signal, scored present/absent, awarding the points shown. The earned total is normalized to 0–100 (111 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 — when the provider publishes it. A derived classification keeps a floor: it is a real artifact an agent can fetch and act on, it is simply not evidence about the provider's design intent.	`agentic_access artifact present (x-agentic-access), graded by author`	10
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.PROVENANCE-GRADED IN 0.6. Across four national banking markets exactly one institution ran a genuinely hosted MCP; in UK insurance the data credited 14.3% of the cohort and the real number was zero. Catalog-wide, 1,882 of 3,046 MCP artifacts are derived candidates with no URL. Twelve points is the third-largest award in this model and it was being paid, more often than not, for a server nobody can connect to.	`common[].type includes MCPServer, graded by whether the provider runs it`	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. Full credit requires the parameter to appear on POST / PATCH / PUT operations in the contract — the difference between a provider saying they support it and a contract an agent can act on.	`OpenAPI mutating operations declare an Idempotency-Key header (verified), else common[].type matches /idempoten/i (documented)`	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. Full credit requires a single error schema referenced across error responses: a typed envelope, not a catalogue of codes in a table.	`OpenAPI $refs a shared error schema across 4xx/5xx responses (verified), else common[].type includes ErrorCatalog / ErrorCodes / 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. Graded in 0.6 because as a bit it ran at roughly 0% across payments and healthcare and discriminated between nobody: full credit at 50%+ of operations carrying an example, half below that, a quarter for a documentation link alone.	`share of operations carrying request/response examples; else an Examples / Code Samples link`	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. Full credit requires the API to surface live rate-limit state in RESPONSE HEADERS, which is what an agent reads mid-run — documented limits tell it the ceiling, headers tell it where it is.	`OpenAPI responses document X-RateLimit-* / RateLimit headers (verified), else a rate_limits artifact or RateLimits link (documented)`	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. RENAMED AND WIDENED IN 0.9 — it was `asyncapi_events` and read only the asyncapi/ directory, which named the artifact rather than the capability and scored a provider false for describing their events the other legal way. A webhook can be described in OpenAPI: 3.1 added a top-level `webhooks` object and `callbacks` predates it. In this catalog 125 providers do exactly that — 87 via `webhooks` across 2,218 events, 39 via `callbacks` — against ZERO who publish AsyncAPI. Both count, equally: the dimension asks whether an agent can read the event surface, not which specification the provider chose to write it in.	`AsyncAPI document, OR webhooks/callbacks objects in the as-published OpenAPI, 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. PROVENANCE-GRADED IN 0.6: 2,018 of 2,274 skill sets in the catalog are API-Evangelist-generated. In UK insurance all 27 were; across all of telecom, provider-published agent skills exist at exactly three companies.	`skills artifact present, graded by who authored it`	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
A2A Agent Card The provider serves a machine-readable agent discovery manifest at the A2A well-known path (/.well-known/agent-card.json, RFC 8615), advertising its identity, capabilities, skills, endpoint and auth. Weighted above agent_skills despite low adoption for a structural reason: an agent card is the only agent surface in this rubric that CANNOT be derived on a provider's behalf — it is served from the provider's own host or it does not exist. Where mcp_server, agent_skills and agentic_access can all credit an artifact API Evangelist authored, this one is provider-published by construction, and so is immune to the provenance defect that distorts the others.	`a2a/<slug>-a2a.yml manifest, graded on conformance.grade against A2A 1.0.0`	8
Dry-Run / Simulate Mode A destructive operation can be planned before it is committed. This is the safest agent-native affordance in existence and the rarest: it lets an agent show a human what it is about to do, or check its own work, without doing it. Every other safety rail in this model limits the damage of an action that has already happened; this one is the only dimension that prevents it.	`OpenAPI: destructive operations expose a dry_run / simulate / preview / validate_only parameter`	4

Sourced from what the catalog already knows — and from v0.6, from the contract itself. Most dimensions read a signal already published: the x-agentic-access contract, an MCP server, Agent Skills, a well-known catalog, an A2A agent card. Four are now read out of the OpenAPI directly and are graded — idempotency, stable error semantics, rate-limit signalling and examples earn full credit only when the behaviour appears in the contract, and half credit when a documentation page merely asserts it. A fifth, dry-run mode, has no documentation proxy at all and is read from the contract or not scored.

Who published it counts — v0.6. Three dimensions are graded on authorship, not just presence. API Evangelist derives artifacts on providers' behalf — candidate MCP tool catalogs, generated Agent Skills, derived agentic-access contracts — and marks each one as it writes it. Those now earn a quarter of the award rather than all of it, because a derived candidate is a real, fetchable artifact but it is not evidence about the provider. And no provider reaches Agent-Native without idempotency and stable error semantics, however high it otherwise scores: an additive score let strengths cover for missing safety rails, which is exactly the API whose agent retries a payment twice.

Planned — deeper, spec-level checks

The 14 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
Agentic Extensions in the Served Contract `agentic_access` credits a provider-authored agentic-access artifact in the catalog. It cannot see whether those classifications reach the contract an agent actually fetches. A provider can hold the full award with an operation-by-operation contract in this catalog and zero `x-agentic-access` extensions in their served OpenAPI — observed, with honestly-labelled artifacts, at the top of the 0.6 distribution. That is the widest remaining gap between declaration and the thing an agent reads at runtime, and closing it needs a fetch of the live spec plus a diff against the catalog copy, not new rubric math. Deepens the provider-level `agentic_access` signal.	`x-agentic-access (and peers) present in the spec the provider serves, not only the catalog artifact`	planned
Declared Artifact Liveness Most operational and commercial checks are presence-only — they credit `common[].type` and never fetch the URL. A StatusPage entry pointing at an auth-gated health endpoint returning 403 scores identically to a real status page; so does a dead link, or a Plans URL serving a marketing page. This is the cheapest certification step available and the natural first one: a periodic HEAD/GET across declared artifacts, grading resolves / wrong-content / dead, feeding a multiplier rather than a new dimension. It is also the step that makes every downstream attestation claim defensible.	`declared common[] URLs resolve, and their content matches the declared type`	planned
Agentic Commerce Protocols Elogic weights protocol support — UCP, ACP, AP2, MCP — at 25% of its commerce index, and Cloudflare tracks x402 and UCP as a fifth layer. This rubric reads none of them. For a catalog whose thesis is that agents will transact, that is a visible hole, and it is arriving fastest in exactly the commerce-adjacent providers this catalog is thickest in. Waiting on a first-party probe of the kind that produced `agent_card`, not on rubric work.	`UCP / ACP / AP2 / x402 support declared or implemented`	planned
Pagination Coverage JAIRF scores pagination as a RATIO of paginated GET resources and this model does not read it at all. Computable from the refined per-tag OpenAPIs the catalog already carries; it needs a resource-classifier to know which GETs return collections, which is the only reason it is not in 0.6.	`share of collection-returning GET operations declaring pagination`	planned
Operation Distinctiveness Whether an agent can tell two operations apart from their descriptions. JAIRF computes it with embeddings; nothing equivalent exists here. The most directly agent-relevant check in a competitor's spec that this rubric lacks.	`embedding distance between operation summaries within a spec`	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. 106 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 7 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 — 106 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 14 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.9.1 · last updated 2026-08-04 · 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.