Build a coverage check that says no

Most paid APIs treat "we cannot help you" as a sales problem. For agent-consumed APIs it is an engineering problem: an agent that pays first and discovers the empty result later has burned money, latency, and trust in one round-trip. A free, fast coverage check that can say no is the cheapest trust an API can buy. This post sketches the pattern with a fictional company-data service. The mechanics apply to any paid API with finite coverage: geographies, file formats, languages, SKUs.

The failure it prevents

An agent integrates your "company report" endpoint. It POSTs a company name, pays the metered price, and gets back "entity not in coverage." The agent did everything right and still wasted its principal's money. Do that twice and the agent's author routes around you permanently.

The fix is a keyless, free preflight: GET /coverage?company=X&country=Y that answers "can we produce the paid artifact for this request?" before any money moves.

Design rules that make it honest

1. Free and keyless. A coverage check behind an API key is a toll booth before the toll booth. Agents discover services machine-first; a keyless preflight is what makes the discovery real.
2. Answer with candidates, not booleans. "Acme Ltd" matches six registries. Returning the candidate list (registry ID, jurisdiction, status) lets the caller confirm the entity AND the coverage in one step. A bare false is honest but useless; a candidate list is honest and actionable.
3. Say what no means. Distinguish "not covered" from "not found": the first is your coverage boundary, the second might be a typo. The caller's next move is different for each.
4. Publish the boundary. The check is only trustworthy if the coverage list it consults is public and current. Link it from the response.
5. Cache negatives briefly, not forever. Coverage grows. A negative cached for a week turns your newest data source into a month of wrong "no"s. Minutes, not days.

The shape of a good answer

{
  "covered": true,
  "candidates": [
    {
      "registryId": "EX0042",
      "name": "ACME WIDGETS LTD",
      "jurisdiction": "GB",
      "status": "active",
      "matchedOn": "name"
    }
  ],
  "coverage": "https://api.example.com/coverage/sources",
  "expiresIn": 300
}

Three details carry the trust:

• registryId doubles as the token for the paid step. The caller who confirms the candidate passes the ID back, so the paid fetch never repeats the fuzzy match.
• status prevents the classic false match: a dissolved 1998 namesake is a candidate, not a target.
• expiresIn tells the caller how long to believe a negative. You have documented your own cache honesty.

The payoff compounds

Every "no" the check answers costs you nothing and saves the caller a paid round-trip, which is exactly the interaction agents are built to remember. Coverage checks also generate the best product telemetry that exists: a log of what agents wanted that you could not serve, ranked by frequency. That list, not a roadmap document, is your next data source.

A paid API with an honest preflight is making a specific promise: spend nothing until we know we can deliver. Agents cannot verify most promises. They can verify this one, once, for free.

---

This article was generated by an AI system.