Recomputable API Scores That Survive Buyer Review

Recomputable API scores give an agent buyer the arithmetic behind a provider ranking. The buyer can reproduce the total from the response instead of accepting a number issued by the same layer that ordered the candidates.

That distinction matters to an API provider. A rank can affect whether an endpoint receives a paid call. If the calculation is reproducible, you can identify the measured fact that changed the order, check that the stated rule was applied, and disagree without alleging that the whole comparison is opaque.

Reproduction starts with one complete response

A methodology page is useful, but it cannot reproduce a particular comparison. The buyer needs the inputs and intermediate values from the request that produced the order.

Keep these fields together as one calculation record:

• The stable `candidate_id` for every reviewed candidate in the comparison.
• The raw value used for each included dimension.
• The normalized 0–100 value for every included candidate and dimension.
• The active weight for price, latency, success rate and input compatibility.
• The contribution each included dimension made to each candidate's total.
• The optimization rule and hard requirements attached to the request.
• Every dimension dropped because the required measurement was unavailable.

The verification is then mechanical. For each candidate, the buyer checks the contribution created by every normalized value and active weight, then adds those contributions. The reproduced total should lead to the returned order. No private interpretation is required.

This is more specific than publishing transparent API scoring weights. Weights disclose what the comparison preferred. Recomputability proves that the disclosed preference, values and contributions lead to the actual returned score.

The candidate set is part of the formula

Apiosk's 0–100 score is relative to the candidates in that one comparison. It is not a permanent quality grade for an endpoint.

Relative normalization makes the shortlist part of the calculation. Add a lower-priced candidate and the price positions can change. Remove the fastest measured candidate and the latency positions can change. The provider did not necessarily become cheaper or faster; the comparison field changed around it.

A saved score without its candidate identifiers is therefore not reproducible. It is also easy to misread. Comparing a provider's total from two different shortlists can suggest an operating change where none occurred. A valid review compares the underlying measurements and the calculation context, not two detached totals.

This is why a useful API comparison at decision time returns the evidence for the current candidate set. A catalogue-wide badge would answer a different question and could not explain the order for the buyer's actual request.

Missing evidence changes the arithmetic openly

Not every candidate has every operating measurement. Measured latency and measured success rate depend on enough proxied calls. A new or lightly observed listing may not have that evidence yet.

Missing is not zero. Zero would claim that the endpoint performed at the bottom of an observed dimension. When no observation supports that claim, scoring it zero would turn the comparison layer's data gap into a provider penalty.

Apiosk drops an unmeasured dimension from the weighting for that candidate and names the omission. A buyer reproducing the score must use the same included dimensions. The omission remains visible, so the buyer can decide whether a calculation based on fewer measurements is sufficient for the workload.

Two boundaries remain outside the arithmetic. Apiosk does not measure result quality or provider terms. Recomputable API scores cannot establish that an endpoint returns the best result or that its terms suit the buyer. They only support the dimensions actually returned by the comparison.

External x402 results do not enter the score either. Discovery can return them separately as `external_candidates`, but they have no `candidate_id`. They are unreviewed, unmeasured and not settleable through Apiosk, so they cannot be passed into the comparison or decision endpoints.

A buyer can disagree without discarding the evidence

Recomputation first checks the published result under the published rule. It can then support a separate question: what would the order be under the buyer's own priorities?

Suppose the response used `optimize_for=balanced`, while an operator later decides that measured reliability should dominate the workload. The operator can retain the same candidate set and measurements, apply a different declared weighting, and inspect whether the order changes. That second result is a buyer-specific calculation, not a correction to the original response.

Keeping those two operations separate prevents a quiet rewrite of history. The original comparison remains attached to its rule. The alternative calculation records the changed preference. If the order changes, both parties can point to the dimension whose contribution moved rather than arguing about which total deserves trust.

Hard constraints are different. A price ceiling, latency ceiling, reliability floor, settlement requirement or required input should determine eligibility before weighting begins. A large contribution in another dimension must not compensate for a failed requirement. Constraint-based API filtering keeps exclusion and ranking as separate operations.

Providers can diagnose a rank from the contribution path

For a provider, the useful output of a reproducible score is not a marketplace-wide number to optimize. It is the path from a measured fact to one buyer's order.

Start with the stage where the endpoint lost. If a hard requirement removed it, inspect the listing field or operating measurement tied to that constraint. If it remained eligible but ranked lower, compare the per-dimension contributions. A price contribution points to commercial positioning. An input compatibility contribution points to the declared schema. A latency or success-rate contribution points to observed calls.

The evidence may also show that no provider action is required. A buyer can legitimately prefer a dimension where another candidate performs better. Recomputability does not promise that your endpoint wins. It lets you distinguish a correct loss under the buyer's rule from a calculation that cannot be verified.

That distinction helps procurement records too. A later reviewer can recreate why a provider was ordered above another without relying on a screenshot or an undocumented model judgment. The score, its inputs and its omissions travel as one inspectable record.

Where Apiosk fits

`GET /v1/compare?candidates={id},{id}` places price, measured latency, measured success rate and input compatibility side by side. Every response carries the weights that produced its relative 0–100 scores and each candidate's contribution per included dimension. Unmeasured dimensions are dropped and named.

`GET /v1/decide?candidates={id},{id}` uses that reviewed candidate set to return one provider, the rule that selected it, each rejected candidate with the exact constraint that removed it, and ordered runners-up. The same comparison is available as `apiosk_compare` over the Apiosk MCP server.

Apiosk supplies the comparison record; the buyer remains free to verify it or test another declared preference. For providers, that means a lower position comes with an inspectable reason rather than an unexplained grade. To join the reviewed set, list your API with its capability, current payment terms and input requirements.