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 111 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.15.1 · 6 bands · 8 facets · 111 checks · 556 points · updated 2026-08-27
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.
A TRACKED SIGNAL, NOT A SCORED ONE. No new dimensions, no weight changes, no change to the 139-point agent-readiness denominator, and no band re-cut — because nothing about any provider’s score moves. Scores stamped 0.15.0 remain correct under 0.15.1.
WHAT IS NEW is a third list in the agent-readiness layer. dimensions are scored.
planned_dimensions are things we cannot measure yet — each blocked on a probe, a parser, a
collection we do not have. observed_signals is neither: fully implemented, running on every
pass, and finding nobody. The detector works; the catalog is empty.
THE FIRST TWO ENTRIES ARE RFC 10008 — the HTTP QUERY method, published as a Proposed Standard
in June 2026. QUERY is safe and idempotent like GET but carries a request body like POST, and
the RFC registers Accept-Query as the response header through which a resource advertises
that it accepts QUERY and which query media types it understands. We track both: the header at
runtime, and the method in the contract.
WHY THIS SIGNAL AND NOT ANOTHER. Every other machine-readable declaration this rubric reads is
a document somewhere else — a spec file, a well-known linkset, an MCP manifest. Accept-Query
is served by the resource, at the resource, at request time. An agent asking whether a search
endpoint speaks a structured query language asks the endpoint. That is a different class of
discovery from anything else scored here.
WHY ZERO POINTS. A dimension no provider can earn is not a measurement, it is a rescale.
Adding four points with zero earners divides every provider by 143 instead of 139 and moves
roughly 1,900 across a band cut without anyone having gotten worse at anything — the
agent_card failure of 0.5.1, where a raised denominator produced demotions that were pure
arithmetic. The standing rule that a denominator change ships with a band re-cut is exactly
what makes that trade not worth paying to distinguish nobody from nobody.
THE ZERO IS THE POINT. Zero of 26,641 providers declare Accept-Query as of 2026-08-27. The
method is three months old and OpenAPI could not describe it at all until 3.2 added
additionalOperations — 3.1’s Path Item Object has a fixed set of method fields with no room
for QUERY. Recording the zero now makes it a baseline rather than a discovery later. Each pass
prints the count; at 25 distinct providers — the headers catalog’s own promotion line, reused
so both catalogs mean the same thing by “in use” — a signal graduates to a scored dimension
with points and a band re-cut.
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.
Facets
The composite is a weighted blend of 8 facets. Each is scored independently from 0 to 100 against its own checks, then weighted in. Six apply to every provider and their weights sum to 100%. Two are conditional — Regulatory Posture applies only to providers whose industry is regulated, and Open Source Surface only to providers whose product is itself open source and whose repository we were able to read.
| 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% |
| Access Clarity | What it costs, what you are permitted to do, and how you get in — plans, pricing, sign-up, terms of service, privacy, finops mapping, compliance/trust. Renamed in 0.12 from "Commercial Clarity". For a free statutory interface, a public-interest open-data API, or a provider whose own OpenAPI states "No authentication, no registration, no rate limit, no quota", there is no commercial surface to measure and only the permission and access questions apply. The word described a subset of the catalog and was read as a deficiency by the rest. | 20% |
| Operational Transparency | Does the provider expose how the API behaves operationally? Rate limits, status, change log, deprecation, security disclosure. | 13% |
| Contract Governance | Artifacts that describe and constrain the CONTRACT — rulesets, vocabulary, declared conformance, overlays. Renamed in 0.12 from "Governance": it never measured how the organisation governs itself, and the standalone `accountability` layer now does, so one word could not carry both. NOTE ON WHAT THIS SCORES (0.12, roadmap#62): these checks read what a ruleset DECLARES, not the result of running it. Spectral is never executed against the provider's own spec. The facet text through 0.11 described lint outcomes, which was the source of a reported and confirmed defect. Outcome-based linting is a separate artifact class and is not in this release. | 12% |
| Discoverability | Can the API be found and understood from machine-readable metadata alone? Driven by apis.yml completeness, tagging, and identity signals. | 10% |
| Regulatory Posture conditional | For providers in a regulated industry ONLY: does the API publish the consent, security, legal, and standards-conformance posture its regime demands? Consent-scoped authorization (OAuth/OIDC scopes), a published security + vulnerability-disclosure posture, terms/privacy as legal basis, and evidence of conformance to the industry's data standard. Not applied to unregulated industries — see the composite math note below. | 15% |
| Open Source Surface conditional | For providers whose product is itself open source ONLY: does the repository publish the maintainership surface a consumer needs in order to depend on it? A vulnerability-disclosure path, a documented contribution route, a published release history, and a stated code of conduct. Not applied to closed-source products — a company with no CONTRIBUTING.md is not deficient, it is differently shaped. Not applied where the repository could not be read, either: unreadable is not missing. | 10% |
base = Σ(weight[f] × facet[f]) # the six base facets, weights sum to 100%
W = Σ(weight[c]) over the conditional facets that APPLY
composite = (1 − W) × base + Σ(weight[c] × facet[c])
neither: composite = base
regulated only: composite = 0.85 × base + 0.15 × regulatory
open source only: composite = 0.9 × base + 0.1 × open_source
both: composite = 0.75 × base + 0.15 × regulatory + 0.1 × open_source- We read it — the facet applies and is scored on what is there. A zero here means we looked and it was not published.
- We could not reach it — the facet does not apply and its checks leave the denominator entirely. A repository we cannot read is not a provider that failed to publish a security policy.
- The product is not open source — the facet does not apply. A company with no CONTRIBUTING.md is not deficient, it is differently shaped.
The 111 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.
Contract Quality
Technical depth and richness of the API contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD.
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.2 The provider publishes OpenAPI 3.2. Scored from the version they published, not from the version our refinement produced: 275 of the 339 providers holding a 3.2 document in the catalog hold it only because refine-openapis upgraded theirs, and exactly three publish 3.2 themselves. Worth the same as 3.1 rather than more — shipping the newest version is good practice, not a different kind of contract. | declared version >= 3.2, read from the provider's published document |
5 |
| 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.0.15.0 MAKES THE LABEL TRUE. Until then this check never resolved anything: a denylist of obvious placeholders, then "has a dot and an alphabetic TLD" — so any host an author invented that missed the denylist counted as callable. `oracle.api.com` was Oracle Hospitality's ENTIRE callable score (1 of 59) and returns no DNS answer. Resolving all 14,061 literal hosts the classifier graded `real` found 829 (5.9%) with no address and 12 cluster-internal, across 392 providers. No lexical rule could have found most of them: a host that was live when harvested and is dead today is indistinguishable from a working one by pattern matching, and that population only grows.Templated hosts are never resolved — `https://{region}.api.acme.com` is callable by a consumer who fills the variable in, and resolving the residue would ask a different question. Only an authoritative negative answer removes credit; timeouts stay unknown and keep it.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 that is not a placeholder host, a bare template variable, or a host an actual DNS resolve found to have no address |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
|---|---|---|
| Documented resource lifecycle Of the resources a provider lets you CREATE, the share that also document how to read the thing back, change it, and remove it. Grouped by RESOURCE, not by path -- REST splits one resource across `POST /things` and `GET|PUT|DELETE /things/{id}`, and a path-level view would score that as two incomplete resources. WHY IT IS A CONTRACT SIGNAL. An agent that creates something and cannot read it back has no way to confirm the write landed, no way to correct it, and no way to clean up after itself. That is a property of the contract, visible in the contract, and orthogonal to everything else this facet measures -- a provider can document one endpoint impeccably, score full marks on tagging, schemas and examples, and tell an agent nothing about what happens next. REWARD-ONLY AND CAPPED. Absence of a documented DELETE is not absence of DELETE: a resource can be genuinely append-only (an event, a log line, an audit record), the capability can exist and be undocumented, or the resource can be managed elsewhere. Only the middle case is a provider deficiency and none of the three is distinguishable by reading the spec, so incompleteness is never penalised. The 0.33 cap means a provider clears this on a healthy third rather than needing 100%, and it stops the check rewarding CRUD-for-its-own-sake -- an API that deliberately exposes no DELETE must not score below a worse one that ships a dangerous one. MEASURED 2026-08-18 over 5,884 providers with a creatable resource: 96,704 creatable resources, 15.5% fully round-trippable, mean provider share 15.6%, MEDIAN 0.0%, and 59.1% documenting not one. This check reads near-zero across the catalog on day one, which IS the finding, and the band re-cut is part of the change rather than a follow-up. TWO CONVENTION BUGS WERE FOUND AND FIXED BEFORE THIS SHIPPED, both by spot-checking providers whose answer could be reasoned about independently rather than by trusting the aggregate. (1) Requiring PUT or PATCH for the update leg scored STRIPE 0.000 on 189 creatable resources -- Stripe uses POST on the instance path and does not use PUT or PATCH anywhere. (2) Not stripping file extensions scored SHOPIFY 0.000 on 166 -- `/customers.json` and `/customers/{id}.json` folded to two different resources. Corrected: Stripe 0.583, Shopify 1.000. KNOWN CAVEAT, recorded rather than hidden: an RPC-style API inflates the denominator. Slack publishes 636 paths and NOT ONE parameter segment (`/calls.add`, `/calls.end`) -- it is not resource-oriented, so 121 of its POST endpoints are counted as creatable resources that can never round-trip. Because this check is reward-only, no such provider is penalised; the effect is that the catalog-wide percentages above UNDERSTATE round-trip coverage among genuinely RESTful APIs. Quote them with that caveat. | share of creatable resources that also document read, update and delete, capped at 0.33 |
5 |
| Implements a domain standard The contract itself declares conformance to an interoperability standard for its market -- a SCIM schema URN, an OData metadata surface, an OpenRTB bid endpoint, a Sparkplug topic namespace, an ActivityPub actor. A customer who already speaks the standard can integrate with no bespoke connector; one who does not needs a bilateral one, and until 0.12 both scored identically. REWARD-ONLY, and that is deliberate. Absence earns nothing and costs nothing, because most markets in this catalog have no domain standard to implement and penalising their providers would measure the market rather than the provider. EVIDENCE, NOT CLAIM -- inherited from reg_mandate_verified, whose own finding was that a claimed-but-unverifiable mandate scored BELOW organizations under no obligation at all. Naming SCIM in marketing copy earns nothing here; declaring `urn:ietf:params:scim:schemas:...` in the contract earns. Measured 2026-08-17: 164 of 7,579 providers with a contract (2.2%) -- OData 89, SCIM 60, ActivityPub 10, OpenRTB 4, Sparkplug 2. Web of Things, oneM2M and HR Open have ZERO detectable adoption. That thinness is why this is a check and not the conditional facet originally proposed. | contract carries a recognised domain-standard signature |
4 |
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 |
|---|---|---|
| Published example corpus A published corpus of worked examples, separate from the contract. DISTINCT FROM `examples_present`, which reads examples INSIDE the OpenAPI document: a provider can reasonably have either or both, and 595 providers declare this pointer while it was read by no check at all. Found by Ahmet Soormally at WunderGraph, who wired nine pointers to his own record unprompted and got nothing for two of them — with nothing in the build that would ever have told him, or us. The catalog already treats examples as first-class: there is an `examples/` artifact class and an api-search/examples site. The rubric was the only part that could not see them. | common[].type includes "Examples" (alias-aware: CodeExamples, Samples, CodeSamples, Demos) |
4 |
Developer Ergonomics
How easy is it to get started? SDKs, CLI, portal, getting-started, documentation, sandbox/console, MCP server, and authentication clarity.
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 |
| 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 |
Access Clarity
What it costs, what you are permitted to do, and how you get in — plans, pricing, sign-up, terms of service, privacy, finops mapping, compliance/trust. Renamed in 0.12 from "Commercial Clarity". For a free statutory interface, a public-interest open-data API, or a provider whose own OpenAPI states "No authentication, no registration, no rate limit, no quota", there is no commercial surface to measure and only the permission and access questions apply. The word described a subset of the catalog and was read as a deficiency by the rest.
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 |
Operational Transparency
Does the provider expose how the API behaves operationally? Rate limits, status, change log, deprecation, security disclosure.
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 or repository — where SDKs, specs, and issues live in the open. WIDENED IN 0.13 (roadmap#71): `GitHubRepository` was read by no check while 600 providers declared it, so a provider pointing at their actual code repository scored below one pointing at an org page. A repository is not an organization, but for the question this check asks — is the code findable — it is the same answer, and often the more precise one. | common[].type includes "GitHubOrganization" or "GitHubRepository" (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 |
Contract Governance
Artifacts that describe and constrain the CONTRACT — rulesets, vocabulary, declared conformance, overlays. Renamed in 0.12 from "Governance": it never measured how the organisation governs itself, and the standalone accountability layer now does, so one word could not carry both. NOTE ON WHAT THIS SCORES (0.12, roadmap#62): these checks read what a ruleset DECLARES, not the result of running it. Spectral is never executed against the provider's own spec. The facet text through 0.11 described lint outcomes, which was the source of a reported and confirmed defect. Outcome-based linting is a separate artifact class and is not in this release.
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 ENFORCED — authored plus whatever an `extends:` brings in. 0.12 (roadmap#62): this counted authored rules only, so a ruleset extending spectral:oas and adding a focused handful was measured on the handful. As the provider who reported it put it, the alternative was "inlining 41 rules I didn't write in order to be measured on the 9 I did". Extending a maintained base is the better engineering choice and the threshold was punishing it. | rules[0].effective_rule_count >= 20 |
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 |
Discoverability
Can the API be found and understood from machine-readable metadata alone? Driven by apis.yml completeness, tagging, and identity signals.
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 THE PROVIDER wrote, or a declared LLMsTxt pointer |
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 |
Regulatory Posture
For providers in a regulated industry ONLY: does the API publish the consent, security, legal, and standards-conformance posture its regime demands? Consent-scoped authorization (OAuth/OIDC scopes), a published security + vulnerability-disclosure posture, terms/privacy as legal basis, and evidence of conformance to the industry's data standard. Not applied to unregulated industries — see the composite math note below.
The consent, security, legal, and standards-conformance posture a regulated-industry API is expected to publish. Scored only where a regime applies; sourced from signals already in the catalog.
| Check | Rule | Points |
|---|---|---|
| Consent-scoped authorization Published OAuth/OIDC scopes — the machine-readable expression of least-privilege, consented access every data-sharing regime is built on. The single strongest regulatory signal. | common[].type includes "OAuthScopes" OR a scopes artifact is present |
10 |
| Authentication model documented A documented authentication/authorization model (OIDC, mTLS, PAR). A regulated API that will not say how it authenticates cannot be trusted to hold the line the regime draws. | common[].type includes "Authentication" or "OpenIDConnect" |
6 |
| Security posture published A published security policy or domain-security posture. Regulated data demands a stated, verifiable security stance, not an assumed one. | common[].type includes "Security" or "DomainSecurity" |
6 |
| Vulnerability disclosure program A VDP / responsible-disclosure channel. For a regulated provider this is table stakes, and its absence is a conspicuous gap. | common[].type includes "VulnerabilityDisclosure" |
6 |
| Terms of service (legal basis) Machine-findable terms establishing the legal basis for access — the contract a regulator expects to exist and be discoverable. | common[].type includes "TermsOfService" |
4 |
| Privacy policy (data handling) A published privacy policy stating how personal/consumer data is handled — the disclosure most regulated regimes require. | common[].type includes "PrivacyPolicy" |
4 |
| Compliance / certification disclosure Published compliance, certification, or trust-center content (SOC 2, ISO 27001, PCI, regime attestations) — evidence the provider holds itself to an external standard, not just its own word. | common[].type includes "Compliance" or "TrustCenter" or "Trust" |
5 |
| Data-standard conformance Evidence the API conforms to the industry's data standard (a named standard, conformance artifact, or a published vocabulary/JSON-LD context). In a regulated space, speaking the mandated shape is the difference between interoperable and merely present. | implements a recognized data standard — common[].type includes "Standard"/"Conformance", or a Vocabulary/JSON-LD context is published |
5 |
| Conforms to the standard named for its regime The provider conforms to the standard RECOGNIZED FOR ITS REGIME, resolved against the standards catalog: OBIE, the DSB Consumer Data Standards, FDX or Berlin Group for open banking; US Core / USCDI for health; ACORD, CIECA or CSIO for insurance; CAMARA or TM Forum for telecom; Green Button / ESPI or cds-energy for energy.This supersedes the generic check above in strength for a reason the banking quartet made plain: a `Standard` tag credits an intention, while naming the instrument credits a fact. It is also the check the insurance quartet needed to state its emptiest finding honestly — ACORD is live inside a machine-readable contract at exactly one company worldwide. | conformance/ declares conformance to a standard listed under the matched regime`s `standards:` — not merely a generic Standard tag |
8 |
| FAPI / hardened authorization profile The security profile CDR, UK Open Banking and PSD2 actually mandate, beyond generic OAuth: the FAPI profile, pushed authorization requests, private_key_jwt client authentication, mTLS-bound tokens. Generic OAuth is table stakes; this is the stack the regime specifies. | conformance declares FAPI or FAPI 2.0, or auth artifacts document PAR, private_key_jwt or mTLS-bound tokens |
6 |
| Published consent model A consent surface a machine can read. This is the structural gap the whole series found and the reason it is weighted where it is: in market after market whose entire premise is consumer consent, machine-readable consent ran in the single digits. A FHIR Consent resource is exposed by essentially nobody; insurance ran at 2.5% in the US and zero among every market's leaders, in the most personally-invasive data business in the economy.Weighted heaviest in insurance and telecom precisely BECAUSE no rule compels it there — where consent is unmandated its presence is a genuine differentiator rather than a compliance artifact. | a machine-readable consent surface — consent scopes, a FHIR Consent resource, a CDR consent artifact, or a documented consent/authorization model |
7 |
| Action / write surface The regime is actionable, not read-only. An agent that can move money on an account is a different animal from one that can only read it, and the score should say so: the UK — which mandated payment initiation — scored 87% on idempotency, where read-only Australia scored 0%. | the contract exposes payment initiation, VRP, or another mutating regulated operation |
4 |
| SMART-on-FHIR configuration served A served `.well-known/smart-configuration` with published SMART-on-FHIR scopes. The structural finding across all four healthcare markets: the security scopes often exist, but the smart-configuration is served almost nowhere — so the check has to weight a DISCOVERABLE, consent-legible surface rather than the mere presence of scopes somewhere in prose. | a .well-known/smart-configuration is served, or SMART scopes are published |
6 |
| PCI scope and strong customer authentication PCI-DSS attestation or scope disclosure together with strong customer authentication (3-D Secure, PSD2 SCA). The two disclosures every payments regime is built on, and the ones a merchant's own auditor will ask for first. | PCI-DSS attestation or scope disclosure, plus 3-D Secure / SCA support |
6 |
| Machine-readable entitlement and redistribution terms Entitlement and redistribution terms in machine-readable form, plus MiFID II or exchange data-licensing disclosure. In market data the licence IS the product boundary, and a consumer who cannot read it programmatically cannot build against it safely. | redistribution / entitlement / data-licensing terms published as machine-readable data |
6 |
| Third-party certification A certification issued and published by somebody other than the provider. Canada runs the only public, tiered insurance API certification programme in the world (CSIO) and it was invisible to the score — its own table lists the country's largest P&C insurer as Not Yet Rated while smaller competitors hold higher tiers, which is exactly the published signal a rubric should read.THE CAUTION THIS CHECK CARRIES, learned from real estate: RESO certification is real, independently tested and industry-mandated, and it is worth 2.0 points of measured difference — because all three certified organizations return 401 on the very contract they are certified against. A certification claim is credited here only alongside `servers_resolvable`; a badge for a document the consumer cannot fetch is not conformance. | a public, independently-issued certification is held and discoverable |
5 |
| CAMARA / network-API conformance Conformance to the network-API standards the sector actually built: CAMARA commonalities, the canonical API definitions, CIBA (the backchannel authentication flow CAMARA specifies for network authorization, found in 3 of 19 standards repositories and absent from both specs of the one exposure platform with a callable endpoint), and TM Forum Open API conformance — held widely by carriers who publish no network API at all. | an x-camara-commonalities version, /camara/ paths, CIBA support, or TM Forum Open API conformance |
6 |
| Mandate implemented, not merely claimed THE LARGEST UNMEASURED EFFECT IN THE CATALOG, and the reason it lands in 0.6 rather than waiting. Across 95 energy organizations scored on a deliberately ruthless mandate ladder, a VERIFIED mandate was worth about twelve points of composite — live-implemented 42.2 against not-applicable 36.6 — while a CLAIMED-but-unverifiable mandate scored 30.4, BELOW the 30.2 of organizations under no obligation at all.That second number is the finding. Self-declared compliance is not merely uninformative, it is NEGATIVE signal, and any assessment that reads compliance pages instead of calling endpoints will rank the field backwards at the top. Compare RESO in real estate at 2.0 points: same question, two sectors, a six-fold difference in effect, because one mandate came with a public register and conformant discovery endpoints and the other came with a badge.The failure mode is already live here: two Ontario utilities present as Green Button compliant and cannot be verified, one because its onboarding host returns HTTP 200 for every path including invented ones, being a single-page-app catch-all. Without a verification state that provider scores as compliant. | the mandated surface is evidenced by a resolvable endpoint, register entry or conformant discovery document — not by a compliance page |
8 |
Open Source Surface
For providers whose product is itself open source ONLY: does the repository publish the maintainership surface a consumer needs in order to depend on it? A vulnerability-disclosure path, a documented contribution route, a published release history, and a stated code of conduct. Not applied to closed-source products — a company with no CONTRIBUTING.md is not deficient, it is differently shaped. Not applied where the repository could not be read, either: unreadable is not missing.
The maintainership surface an open-source API product publishes on its own repository. Scored ONLY where we hold a live successful read of that repository — harvested directly from the GitHub API, never inferred from the pointers in apis.yml.WHY NOT READ THE POINTERS. Every other provider-level check in this rubric reads common[]. These deliberately do not. A pointer records that WE wired something; the harvest records that the PROVIDER published something. Scoring the pointer would dock a provider for catalog work we had not got to — the two-sided attribution failure these cohort passes exist to catch.This was not theoretical. 647 of the 1,151 records in the first evidence file had been RECONSTRUCTED from apis.yml pointers after a partial run clobbered the originals, and they disagreed with a live read systematically: CodeOfConduct +22.2 points, ContributionGuide +18.0, SecurityPolicy +13.9, and not a single provider holding only one signal against 21% in the live set. Reconstruction can only recover what somebody had already wired, so sparse providers had nothing to reconstruct from and vanished. All 647 were re-harvested live before this facet shipped, and reconstructed records are excluded from the facet by score.rb regardless.IssueTracker IS DELIBERATELY NOT A CHECK. It reads 100.0% across all 1,148 live-harvested repositories, because the harvester derives /issues from the repository URL and every GitHub repo has one. It is not an observation of the provider. Scoring it would hand free points out for existing.
| Check | Rule | Points |
|---|---|---|
| Published vulnerability-disclosure path Where an integrator reports a vulnerability in the thing they just put into production. The rarest of the four at 35.0% and the one that most directly affects a consumer, which is why it carries the most points. | a SECURITY policy is present on the provider's own product repository |
14 |
| Documented contribution route Whether the project is actually open to participation or merely published. 62.4% coverage. | a CONTRIBUTING guide is present on the provider's own product repository |
10 |
| Published release history Versioned, dated artifacts — the thing a consumer checks before depending on a project. Commonest of the four at 76.0%, but priced above the code of conduct because it carries far more information about whether the project is maintained. | the provider's own product repository publishes releases |
10 |
| Stated code of conduct A stated standard for participation. Priced lowest of the four despite being rarer than releases at 49.6%: it is the most template-prone signal in the set, frequently dropped in wholesale, and so says the least about the project that holds it. | a CODE_OF_CONDUCT is present on the provider's own product repository |
6 |
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.
Agent Readiness Bands
The 19 Dimensions
Each dimension is a provider-level signal, scored present/absent, awarding the points shown. The earned total is normalized to 0–100 (139 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 |
| Documented Reversibility Does the contract say what can be UNDONE, how, and within what window. roadmap#68 proposed this over a consequence multiplier on dry-run and idempotency, and preferred it for a reason that holds up: a multiplier needs whole markets classified by hazard, which is the hard part, while this measures something no dimension covers and needs no such classification. It is what an agent actually needs BEFORE it acts. Dry-run lets it rehearse and idempotency stops it double-firing; neither tells it whether the action it is about to take can be taken back. GRADED. `documented` = a reversal operation exists in the contract (cancel, refund, void, reverse, undo, rollback, restore). `verified` = that AND a stated window (grace_period, cancellation_window, "within 30 days"). A path says the capability exists; the window is what makes it plannable. A window with NO reversal operation behind it earns nothing -- that is a policy sentence, not a capability. MEASURED 2026-08-18 across 7,579 providers holding a contract: 1,353 (17.8%) expose a reversal operation, 343 (4.5%) document a window, 171 (2.3%) do both. It discriminates without being near-empty, which is what a new dimension has to clear. GATED ON WRITE SURFACE like the other hazard dimensions: a read-only API has nothing to reverse, and a zero there would measure the absence of a hazard rather than the absence of work. | a reversal operation in the contract, graded up when a window is documented too |
6 |
| 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. | deployment.mode + probe verdict on the mcp/ manifest, not the pointer; an unprobed slug falls back to authorship |
12 |
| Machine-Readable Auth Can an agent authenticate in a way that is bound to it, or only bear a secret? Graded in 0.12.2 (roadmap#97): this credited presence and stopped, so `apiKey` earned the same ten points as OIDC. IETF draft-klrc-aiagent-auth-00 calls static API keys "an antipattern for agent identity — bearer artifacts that are not cryptographically bound, do not convey identity, are typically long-lived and are operationally difficult to rotate". A dimension named Machine-Readable Auth was paying top price for the artifact the field is converging on calling unsuitable. THE FLOOR IS 0.35 AND NOT ZERO, deliberately: a documented API key is still machine-readable auth, and zeroing the 2,209 providers who declare only `apiKey` would measure the market rather than the provider. Read from the refined per-tag OpenAPIs, which already carry `securitySchemes` — no probe and no new artifact. The apis.yml pointer remains a FALLBACK grading `bearer`, so a provider whose specs we have not indexed is not zeroed for our own gap; a pointer cannot name a scheme class. THE ID STAYS `auth_clarity` ON PURPOSE. `auth_scheme_strength` in planned_dimensions describes this change, but the dimension id is POSITIONAL — DIM_ORDER in build_listings.py and DIMENSIONS in the glyph both encode by slot — so renaming it is a coordinated four-place change of the kind roadmap#89 documents. The regrade is the value; the rename is cosmetic and can ride a future glyph release. Same reasoning as the `emits_as` facet aliases. | a served openid-configuration/oauth-authorization-server carrying `issuer` (served), else the securitySchemes class in the provider OpenAPIs — bound (mutualTLS, DPoP, Signature) > negotiable (oauth2 authorizationCode/clientCredentials, openIdConnect) > bearer (http bearer, apiKey) |
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. SecurityTxt was accepted here until 0.15.0 and earned 93% of the credit — an RFC 9116 vulnerability-disclosure contact expresses no AI usage preference and identifies no agent. It still scores under well_known_published, which is where a /.well-known/ document belongs. | common[].type includes AIPREF, ContentSignal, WebBotAuth, or HTTPMessageSignatures |
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 |
| Delegated User Identity Can a caller obtain a token scoped to the HUMAN it is acting for, or only a credential belonging to the integration itself? Section 10.3 of draft-klrc-aiagent-auth-00 splits exactly this way — the user delegates authorization, versus the agent obtains its own — and nothing in this rubric distinguished them. It is the difference between an audit log that can name a delegated subject and one that cannot, which Section 11 of that draft makes a MUST. DISTINCT FROM `auth_clarity` on purpose. A provider can hold strong bound credentials and still offer no delegation path, and the reverse is equally possible; scoring them as one dimension would let a strong answer to one question hide a missing answer to the other. MEASURED BEFORE IT WAS BUILT: 768 providers declare `authorizationCode`, ~67% of the 1,142 declaring any oauth2 and 20x the `openIdConnect` population. That discriminating power is what separates it from `agent_identity_declared`, which stays parked at 13 providers. ADDED AT SLOT 16, APPENDED. Dimension order is positional in DIM_ORDER and in the glyph; appending shifts nothing, inserting would shift every slot after it. | a served discovery document listing authorization_code in grant_types_supported (served), else an oauth2 authorizationCode flow or openIdConnect declared in an OpenAPI (documented) |
6 |
| Protected Resource Metadata RFC 9728. Section 10.9.2 of draft-klrc-aiagent-auth-00 — an agent discovers HOW a resource is protected and WHICH authorization server protects it, at runtime, instead of being configured by a human. It is the ONLY part of that draft's composition that is a fetchable artifact at the provider's own domain; WIMSE identifiers, attestation and Transaction Tokens all live inside provider infrastructure and cannot be observed from outside. `resource` is the required field. `authorization_servers` is what makes the document actionable — without it an agent learns the resource is protected but not by whom, which describes a lock and not the key. NOT PROBED BY STATUS CODE. api.slack.com answers 200 text/html to this path and to both OAuth metadata paths — a docs-site catch-all — so a status probe would award full credit three times over to a provider serving none of them. The saved BODY is read and the required field tested. | a served /.well-known/oauth-protected-resource carrying `resource` (documented), and naming its authorization_servers (verified) |
5 |
| Registration Without a Human RFC 7591. Section 10.9.3 — if every new agent needs a developer to fill in a portal form and paste a key, the provider has no agent onboarding path regardless of what its docs claim. `console_or_sandbox` and `sign_up_present` measure the HUMAN onboarding path only; this is the machine one. Costs ONE JSON KEY rather than a probe: `registration_endpoint` is a field of the discovery document the pipeline already fetches and saves on 889 providers. APPENDED AT SLOT 18. Dimension order is positional in DIM_ORDER and the glyph. | a `registration_endpoint` in the served RFC 8414 / OIDC discovery document |
6 |
| Agentic Commerce Surface 197 providers hold a real, parsing `/.well-known/ucp.json` and every one scored zero before this: `well_known_catalog` credits only api-catalog, security.txt and protected-resource, and NONE of the 197 holds any of those. A provider standing up a conformant agentic-commerce document was indistinguishable from one serving no `.well-known` at all. OPERATOR ATTRIBUTION IS SETTLED BEFORE THE AWARD. 193 of the 197 point at `<store>.myshopify.com` — that is not 193 merchants shipping an agentic-commerce surface, it is one platform shipping one 193 times under its merchants' names, the same failure that ranked universities for Figshare's contract. The grade is decided from the document's own service endpoints: on the provider's registrable domain it is theirs; on a vendor's it is real, visible, and the vendor's. `platform` is graded down rather than zeroed because the capability genuinely exists — a buyer's agent can transact there. A PARSING DOCUMENT IS NOT ENOUGH: a version and at least one declared service are required, or it is a stub at the right path. NO AP2 CHECK AND NO x402 CHECK. AP2 defines no well-known path and no pointer — its artifacts are SD-JWT mandate chains presented in-band at transaction time, under authentication, so nothing anonymous is ever fetchable; 0 of the 197 UCP documents reference it. x402 is a 402 plus a response header and needs a live request to a paid endpoint. Scoring either would claim a measurement the surface does not permit — the rule the rubric already applies to draft-klrc-aiagent-auth. APPENDED AT SLOT 19. | a parsing /.well-known/ucp.json or acp.json declaring a version and at least one service — `self` when its endpoints are on the provider's own domain, `platform` when they are on a vendor's |
5 |
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.
Planned — deeper, spec-level checks
The 19 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 |
| 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 |
Bound vs Bearer Authentication
Regrade, not a new dimension. `auth_clarity` reads presence and stops: `apiKey` earns the same 10 points as `openIdConnect`. Proposed credit — bound (mutualTLS, or an http scheme naming DPoP/Signature) 1.00; negotiable (oauth2 with an authorizationCode or clientCredentials flow, or openIdConnect) 0.75; bearer-only (http bearer, apiKey) 0.35. The floor stays well above zero on purpose: a documented API key is still machine-readable auth, and zeroing 2,209 providers would measure the market rather than them. Readable TODAY from the refined per-tag OpenAPIs — no probe, no new artifact. Deepens the provider-level auth_clarity signal.
|
grade auth_clarity by scheme class rather than crediting any declared scheme equally |
planned |
| Workload Identity for Callers Sections 5-6 — the identifier and its cryptographic binding, the actual spine of the draft. Almost certainly near-empty on the public API surface today: 13 providers in the catalog declare mutualTLS at all, and workload identity currently lives inside private meshes rather than at a public edge. Parked deliberately, not dropped. Re-measure before building it; a dimension nobody can earn measures the market, not the provider, and belongs in a report finding rather than in a score. | WIMSE/SPIFFE identifiers, WIT/SVID credentials, or Workload-Proof-Token accepted at the API surface |
planned |
Regulatory Applicability Map
Regulatory Posture only applies if you are in one of these industries. A provider matches a regime when its tags match the regime’s tags; where several match, the one with the most matches wins, ties broken by specificity. Tags listed as ambiguous count only when no other regime matched on a strong tag — they exist because words like broker and exchange mean different things in different industries.
This map is published because it is the part of the rubric a provider is most likely to find wrong about themselves. If your organization is matched to a regime it has no obligation under, that is our defect, not yours — open an issue on your provider repo and we will correct the map.
| Industry | Regimes | Matches on these tags |
|---|---|---|
| Banking & Open Finance | CDR (Australia), UK Open Banking, PSD2/PSD3 (EU), 1033 (US), FDX | banksbankingopen bankingopen financecdrconsumer data rightpsd2psd31033fdxconsumer bankingneobankbuilding societycredit unionmutual bankdigital bank |
| Securities & Market Data | MiFID II (EU), SEC/FINRA (US), exchange data licensing, market-data redistribution | market datasecuritiesstock exchangeorder executionmifidmifid iifinrasecotcderivativesequitiesmarket-databroker-dealerbroker dealerprime brokeragealgorithmic tradingelectronic tradingproprietary tradingstock tradingspot tradingfx tradingforex tradingcopy tradingsocial tradingoptions tradingfutures tradingexchange-traded fundexchange traded fundetfdecentralized exchangecryptocurrency exchangecrypto exchangesecurities lendingmarket makermarket makingorder booktrading platformtrading apibrokerage accountambiguous: exchangebrokeragebrokertrading |
| Health | HIPAA (US), FHIR / US Core, 21st Century Cures Act, EHDS (EU) | healthhealthcareclinicalehremrfhirmedicalpatienthealth datalife sciencespharmatelehealthpayerprovider network |
| Payments | PCI-DSS, card-network rules, SCA/PSD2, ISO 20022 | paymentspaymentcardcardsacquiringissuingpcipci-dssmerchantcheckoutwalletpayment gateway |
| Insurance | NAIC/solvency, open insurance, IDD (EU), state DOI rules | insuranceinsurtechunderwritingclaimspolicyactuarialreinsurancebroker networklloydssyndicatep&clife insurancehealth insurancegeneral insurance |
| Telecommunications | FCC / Communications Act (CPNI), Ofcom / Communications Act 2003, ACMA / Telecommunications Act, ITU Constitution, ePrivacy Directive | telecomtelecommunicationstelcocarriermobile network operatormnomvnocpaassmsnetwork apicamaraopen gatewaysimroamingnumber verificationsubscriber |
| Energy & Utilities | CDR Energy (Australia), Green Button / ESPI (North America), Smart Energy Code + DCC (GB), Ofgem Data Best Practice, FERC Order 889 / OASIS (US) | energyutilitiesutilityelectricitygaspowergridsmart metersmart meteringdistribution networkdsodnoenergy retailergreen buttonrenewablesev chargingwater utility |
| Education & Research | FERPA (US), Title IV / IPEDS (US), UK GDPR + Equality Act 2010, GDPR (EU), UGC (India), PIPA (Korea), QAA (UK) | universityuniversitieshigher educationcollegecampusstudentstudent information systemsisacademicresearch informationinstitutional repositoryscholarlylearning managementlmsedtecheducationschoolregistraradmissionscoursewarelibrary |
| Government & Public Sector | FedRAMP, eIDAS (EU), open-data standards, national gov API policy | governmentpublic sectorgovgovtechcivicmunicipalfederalstate governmentopen datapublic data |
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, afacet, apointsvalue, and arule— the predicate the scorer evaluates. “every api hashumanURL” awards 5 points toward Discoverability. 111 checks run today acrossapis.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 six base sub-scores are blended using the weights above. Each conditional facet that applies — Regulatory Posture at 15% if the industry is regulated, Open Source Surface at 10% if the product is open source and we read its repository — takes its slice and damps the blend by that much. Both can apply at once — see the composite math.
- 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/fallinglabel 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.
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 — plus a seventh for a provider in a regulated industry, and an eighth for one whose product is itself open source — the agent-readiness score is a set of 19 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.
If a conditional facet applies to you, your facet gains are damped. While one is in play, raising a base facet moves the composite by less than its nominal weight — 85% under Regulatory Posture alone, so a 10-point gain on a 20%-weight facet is worth 1.7 composite points rather than 2.0. If both conditional facets apply, base gains are damped to 75%. The remaining leverage is in the conditional checks themselves, and those are usually the cheapest points on this page: a SECURITY.md is one file.
Check the applicability map below: if the regime we matched is wrong for your business, tell us on your provider repo and we will correct it rather than ask you to publish a posture you have no obligation to hold. The same holds for Open Source Surface — if we have the wrong repository, or your product is not open source and we have scored it as though it were, tell us and we will drop the facet rather than have you publish against it.
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 every facet that applies to you, 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
strongorexemplarpill 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_versionreflects a snapshot of what was measured. The rubric evolves deliberately as new artifact types — MCP servers, Agent Skills,llms.txtmanifests — 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.15.1 · last updated
2026-08-27· 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.