API Rating

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 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.

The rating system runs against the catalog on every rebuild and ships with a versioned rubric. The current rubric is v0.3.

Bands

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

Exemplar

70 – 100

Reference-quality API operations across all facets (top ~1% of providers).

Strong

60 – 69

Solid contracts, transparent operations, easy to start (top ~5%).

Developing

45 – 59

Real signal across most facets with visible gaps.

Thin

30 – 44

Limited machine-readable signal; partial portal coverage.

Minimal

0 – 29

Index entry only; little beyond a description and link.

In addition to a band, providers also carry a trending marker — rising, flat, or falling — based on week-over-week change in composite score. A delta of +5 or more marks rising; −5 or worse marks falling. Trending labels populate after at least two scoring snapshots exist in the history window.

The composite is a weighted blend of six facets. Each facet is scored independently from 0 to 100 against a set of artifact-driven checks, then weighted into the composite.

Facet	What it measures	Weight
Discoverability	Can the API be found and understood from machine-readable metadata alone? Driven by `apis.yml` completeness, tagging, identity signals (image, maintainer, dates), and basic API shape (humanURL, baseURL per API).	10%
Contract Quality	Technical depth and richness of the API contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD, Naftiko capabilities. Highest-weighted facet because contracts are what other systems integrate against.	25%
Governance	Spectral rulesets, change logs, deprecation policies, versioning conventions, and license/commons signals. Tracks whether the API is run as a long-lived contract rather than a moving target.	12%
Operational Transparency	Rate limits, status pages, change logs, deprecation timelines, security disclosure policies. Tracks whether operating the API integration is predictable for a downstream consumer.	13%
Developer Ergonomics	SDKs, CLI tools, developer portals, getting-started guides, API references, sandbox/console availability, MCP server availability, and clarity of authentication. The "how fast can I make my first call" facet.	20%
Commercial Clarity	Are commercial terms machine-readable? Plans, pricing, sign-up flow, terms of service, privacy policy, FinOps mapping, compliance and trust signals.	20%

Each facet is rendered as a filled horizontal bar on the provider page. Bars colored gray (0–39) flag weakness; orange (40–69) flag a mid-tier; green (70–100) flag strength.

How a Score is Computed

The rubric lives at signals/_data/scoring.yml and is the single source of truth.

The flow:

Per-artifact checks. Each check has an id, a facet, a points value, and a rule (a free-text description of the predicate). Example: “every api has humanURL” awards 5 points toward Discoverability. Roughly 80 distinct checks run today across apis.yml, OpenAPI specs, AsyncAPI specs, JSON Schema, plans, rate-limits, FinOps, governance artifacts, MCP servers, and JSON-LD contexts.
Facet sub-score. A facet’s raw score is the sum of awarded points. The raw score is normalized against the facet’s maximum possible points to yield a 0–100 sub-score.
Composite. The 6 facet sub-scores are blended into the composite using the weights above. A score of 100 means every check passed at every facet — currently unachievable since some checks require artifacts no provider in the catalog has yet.
Band. The composite maps to one of the 5 bands using the thresholds above.
Trending. If a prior snapshot exists in the history window (12 weeks), the score is compared against the most recent prior snapshot and a rising / flat / falling label is attached.

The score is 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 visible at the top of every provider page.

Phase 1 vs Phase 2. Phase 1 (current) computes the score from artifact presence as declared in apis.yml and the surrounding repository structure. Phase 2 will add deep parsing of OpenAPI/AsyncAPI specifications so that Contract Quality can score on the actual richness of the contract (operations, schemas, examples, security scheme depth, etc.) rather than presence alone. Until Phase 2 ships, the Contract Quality sub-score is 0 for every provider, which means the composite has roughly a 25-point ceiling lower than it will eventually have. Cross-provider comparisons within the current phase remain meaningful.

What the Rating is For

The rating is intended to be useful in two directions:

For developers and agents picking providers. A search result with a band-pill of strong or exemplar is a signal that the provider has invested in making the API actually consumable — readable contracts, predictable operations, transparent commercials. The search at the homepage of APIs.io blends the composite score into result ranking, so high-rated providers float to the top of relevance-matched results.
For providers improving their API surface. Every provider page surfaces the 6 facet bars, making it explicit which aspects of the public API surface are dragging the composite down. The rubric is open — providers can see exactly which checks they’re failing and ship the missing artifacts to raise their score.

What the Rating is Not

Not a quality judgment of the provider’s product. A great product can ship with thin API documentation; a mediocre product can ship with exemplary documentation. The rating measures the documentation and contract surface, not the product behind it.
Not a security audit. The Governance facet includes security disclosure signals but does not assess actual security posture.
Not a compliance certification. The Commercial Clarity facet looks at presence of ToS/Privacy/FinOps signals; it does not certify any specific regulatory standard.
Not stable across rubric versions. Each rubric version (schema_version in the score block) reflects a snapshot of what was being measured. The rubric is intentionally evolving as new artifact types (MCP servers, agent skills, llms.txt manifests, etc.) become standard.

Source

Rubric: signals/_data/scoring.yml
Scorer: signals/score.rb
History snapshots: signals/_data/history/<date>.json — one per scoring run, retained for trend calculation
Current version: schema v0.3 · last_updated 2026-05-19 · maintainer [email protected]