Capabilities and endpoints
A capability is a task, such as finding a work email. An endpoint is one vendor's API call for it. Both live in one typed catalog.
The catalog describes every vendor API in the same shape. Browse it at /providers and /capabilities, or read it from the public catalog API.
Capability
A capability is a task with a fixed contract, whichever vendor performs it. people.email.find,
for example:
| Part | Value |
|---|---|
| Inputs | first_name, last_name, domain (all required) |
| Output fields | email, confidence (0–100) |
| Hit | A deliverable or accept-all email address is returned |
| Accuracy | Share of returned addresses that do not hard-bounce within 7 days |
The hit definition is what makes vendors comparable: routing stops on it, per-success pricing charges on it, and quality scores count it.
Capabilities today include people.email.find, email.verify, people.enrich,
people.profile.find, people.role.find, people.search, phone.mobile.find,
company.enrich and signals.job_change.
Endpoint
An endpoint is one vendor's implementation, named <vendor>/<endpoint>:
hunter/email.find. It declares:
- its input schema (Hunter's is
first_name,last_nameanddomain), - how the vendor's response maps to the capability's output fields, and what counts as a hit,
- its pricing model and list price,
- which credentials it accepts:
byok(your key),managed(GridRouter's account) or both, - how the vendor bills your own key, for billing verification.
GET /v1/catalog/endpoints/{provider}/{endpoint} returns all of it, including the input as JSON
Schema, the current quote and quality.
Pricing models
| Model | Charged |
|---|---|
per_call | Whenever the vendor answers, hit or not |
per_success | Only on a hit (a miss can carry its own, usually zero, rate) |
per_result | Per returned record |
per_unit | Per unit of input or output (rows, domains, credits, pages) |
per_token | Per million tokens, read from the response |
async_task | A submit fee plus a completion fee charged only on success |
Prices are integer micro-USD. POST /v1/quote/{provider}/{endpoint} returns the quote for a given
input without calling the vendor. On your own vendor keys GridRouter charges nothing, whatever the
model.
Quality
Every endpoint's quality comes from real traffic: reliability, coverage (fill), accuracy,
freshness, speed (p50 and p95 latency) and value (cost per verified hit). Rates are Wilson lower
bounds, so a small sample cannot rank high. The composite weighs accuracy 0.30, coverage 0.25,
reliability 0.20, freshness 0.10, speed 0.10 and reviews 0.05, and needs at least 200 calls; below
that, pages show "insufficient data". Use it with sort: "quality" when
routing.