Liveness Checks in API Discovery: What a Probe Can Prove

Liveness checks in API discovery are the cheapest honesty test a catalogue can run. A listing that nobody has called is a claim, and some share of claims in any large index point at endpoints that no longer resolve, no longer sell, or never matched their description. A probe before listing catches most of those. The trouble starts when the result of that probe is treated as more than it is.

A listing nobody has called is a claim

Discovery sources fill up faster than anyone calls them. Crawlers import endpoints, providers submit them, and directories copy from each other. Nothing in that process requires the endpoint to answer.

For an agent, a dead listing is not free. It costs a request, a timeout, and a retry against the next candidate, and if it sits high in the results it costs that on every search. For the providers whose endpoints do work, dead listings dilute the results they appear in. This is the problem a trust boundary between reviewed and unreviewed listings exists to contain, and liveness is the first, crudest filter on the unreviewed side of it.

What an unpaid probe can catch

For a paid endpoint, a useful liveness check sends the request a buyer would send, without payment, and inspects what comes back. The expected answer is a 402 response with a payment challenge. Everything else is a finding.

A probe of that kind catches:

• DNS names that no longer resolve and hosts that refuse connections.
• Expired or mismatched TLS certificates.
• Timeouts before any response arrives.
• Redirects to a homepage, a login page or a parked domain.
• A 200 where a payment challenge was expected, which usually means the route was left open or replaced.
• A 404 or 5xx on the advertised path, which means the route moved or broke.
• A 402 whose challenge is malformed or missing required fields.
• A challenge whose payment terms disagree with what the listing advertises.

The last item is the most valuable and the least checked. An endpoint can be alive and still be misrepresented. When the live challenge and the discovery document disagree, one of them is stale, and an agent that budgets against the listing will be surprised by the gateway.

What a probe cannot tell you

An endpoint can answer a 402 challenge indefinitely and never deliver a paid result. The challenge is often generated by middleware that sits in front of the handler, so a perfect liveness record says nothing about whether the code behind it still works.

A probe also cannot tell you:

• Whether a paid call returns a usable response, which is the distinction drawn in what counts as a successful API call.
• How long a paid call takes. The challenge path is usually much lighter than the work behind it, so challenge latency understates real latency.
• How the endpoint behaves under real inputs, including the edge cases that only appear with production data.
• Whether payment settles correctly, or whether the buyer is charged once.
• Anything about result quality or provider terms.

So probe data belongs in a listing's status, not in its score. Calling it uptime is accurate. Calling it reliability is not, and folding it into a success rate would overstate reliability for exactly the endpoints that fail after payment.

Turning probe results into a listing policy

A probe is only as useful as the rule that acts on it. A few principles keep that rule fair to providers and useful to agents.

Act on patterns, not single events. One timeout can come from a transient network problem on either side. Demote an endpoint after several consecutive failures, and remove it only when failures persist over a longer window.

Classify failures rather than counting them. A DNS failure, a certificate error and a challenge that disagrees with the listing need different responses. The first suggests the endpoint is gone. The second can be fixed in an afternoon. The third may mean the listing is wrong rather than the endpoint.

Show the evidence. Publish when an endpoint was last probed, when it last passed, and what the most recent failure was. An agent can then decide for itself whether a listing last confirmed a week ago is worth a call.

Keep the probe honest about its vantage point. A check from one location reports what that location sees. Regional routing, rate limits on unpaid requests, or blocks on known probe addresses can all produce false failures.

What providers should do about it

From the provider side, liveness checks are the easiest part of discovery to pass, and failing them is an avoidable way to disappear from results.

Return a well-formed 402 to an unpaid request on every paid route, generated from the same configuration that settles paid calls. Keep the payment terms in that challenge identical to those in your discovery document. When you retire a route, redirect it or remove it from your listings rather than leaving it to time out. And do not rate-limit unpaid requests so aggressively that a periodic check reads as an outage.

For a new endpoint with no traffic, a clean liveness record is often the only evidence a buyer has. It does not substitute for measurement, but it is the floor that makes a first paid call reasonable, which is the problem described in cold start for a new paid API.

Where Apiosk fits

Apiosk keeps presence and measurement apart. `GET /v1/discover?q=…` returns reviewed catalogue candidates with a stable `candidate_id`, and sweeps external x402 sources into a separate `external_candidates` block with no ID. Those external hits are unreviewed and unmeasured, and they cannot chain into `/v1/compare` or `/v1/decide`. An external endpoint that answers its challenge perfectly is still on the unreviewed side of that line.

For reviewed candidates, latency and success rate in `/v1/compare` come from calls Apiosk has proxied, and only for listings with enough of them. Where a candidate has not been measured, the dimension is dropped from the weighting and named rather than scored as zero, and Apiosk does not measure result quality or provider terms. The live payment terms for the gateway itself are always at `https://gateway.apiosk.com/.well-known/x402`.

If your endpoint passes its liveness checks and you want buyers to see more than that, list it as a reviewed provider so that paid calls, not probes, become its record.