Transparent API Scoring Weights Buyers Can Audit

Transparent API scoring weights let an API provider see why one endpoint ranked above another. A single 0–100 score cannot do that job because it hides the preferences, measurements and arithmetic that produced the number.

For a provider, the missing detail matters. A lower score might mean the buyer prioritized price, another candidate had better measured latency, or your listing lacked enough observations for an operating dimension. Those situations call for different responses. A score is only an argument when the comparison response carries enough evidence to recompute it.

A total without its parts is not an explanation

A provider score compresses several facts into one ordering signal. That compression helps an agent choose, but it removes context unless the parts ship with the total.

An auditable comparison needs to return at least:

• The candidate identifiers included in this comparison.
• The raw value used for every measured dimension.
• The normalized 0–100 value for each included dimension.
• The active weight assigned to each dimension.
• Each dimension's contribution to each candidate's total.
• Every dimension omitted because a measurement was unavailable.
• The optimization rule and hard requirements supplied by the buyer.

With those fields, an operator can multiply each normalized value by its weight, add the contributions and reach the returned total. Without them, the number is a conclusion with no inspectable path behind it.

This is narrower than a general claim that a marketplace has a fair methodology. The response for the actual request must explain the actual ranking. That is what turns an auditable API provider choice from policy language into a record someone can check.

Weights state preference, not truth

A weight says how much one measured dimension matters for this decision. It does not say that the dimension is universally important, and it does not prove that the underlying measurement is correct.

Consider the same two eligible providers under different buyer instructions. With `optimize_for=price`, the price contribution should carry more influence. With `optimize_for=latency`, measured latency should matter more. A balanced rule distributes influence across the available dimensions. The endpoints have not changed. The buyer's preference has.

Returning the weights makes that preference visible. It also lets a provider distinguish a commercial mismatch from an operating one. If your endpoint loses because price has the largest weight, reducing latency may not change the order. If the latency contribution decides the result, the provider can inspect whether the measured operating data reflects current performance.

Transparent weights do not remove judgment. They locate it. The buyer supplies requirements and an optimization rule; the comparison applies those preferences to the measured candidate set. This is why comparison at agent decision time should return an explanation rather than only a winner.

Hard constraints belong before weighted scoring

Weighted scoring is useful for ranking candidates that are allowed to win. It should not compensate for a failed requirement.

The shared Apiosk parameters include `max_price`, `max_latency_ms`, `min_reliability`, `settlement`, `require_all_inputs` and `optimize_for`. The first group can constrain eligibility. The optimization rule orders the candidates that remain.

Suppose a buyer sets `max_price`. A candidate above that ceiling should be rejected before ranking, even if its measured latency would create a large positive contribution. Letting a high score erase the ceiling would turn a hard rule into a soft preference. The budget-bound API selection process explains why that difference must survive into the decision record.

The same principle applies to required inputs and settlement choice. First determine which reviewed candidates satisfy the request. Then calculate relative scores for the eligible set. A transparent response keeps the two stages separate so a provider can see whether it was excluded or merely ranked below the winner.

Relative scores need their candidate set

Apiosk's 0–100 dimension scores are relative to the candidates in one comparison. The number describes how a candidate performs within that shortlist, not its permanent grade across the marketplace.

That boundary prevents a common reading error. A provider scoring 78 in one comparison and 66 in another has not necessarily deteriorated. The second request may contain a stronger competitor, a different optimization rule or a different set of available measurements. The comparison context changed, so the normalized result changed with it.

For the same reason, a stored score should never be separated from:

• The candidate set used to create it.
• The weights and optimization rule active at that time.
• The measurements included in the calculation.
• The omitted dimensions named by the response.
• The hard constraints applied before scoring.

This context makes later review possible. An operator can reconstruct why the provider won on that request instead of treating the score as a lasting badge. A provider can compare like with like rather than chasing movement caused by a different shortlist.

Missing data is not a zero

Measured latency and success rate require enough proxied calls. Some listings will not yet have those operating measurements. Treating an unavailable measurement as zero would make an unsupported negative claim about the provider.

Apiosk instead drops an unmeasured dimension from the weighting for that candidate and names the omission. The remaining weights produce the comparison from available evidence. That approach is not the same as saying missing data has no consequence. A buyer sees that the conclusion rests on fewer observed dimensions and can decide whether the evidence is sufficient.

The boundary also applies to dimensions Apiosk does not measure anywhere. Result quality and provider terms are outside the score. A high total cannot establish that an endpoint returns the best answer, has acceptable legal terms or fits a buyer's private quality benchmark. Transparent API scoring weights make the included calculation inspectable; they do not expand what was observed.

External x402 discovery results remain outside this calculation. `GET /v1/discover?q=…` can return them in `external_candidates`, but those entries have no `candidate_id`. They are unreviewed, unmeasured and not settleable through Apiosk, so they cannot enter `GET /v1/compare` or `GET /v1/decide`.

Read the contribution before changing your endpoint

For an API provider, the useful question is not “How do I raise my score?” It is “Which measured fact affected this buyer's decision?” The contribution breakdown answers that request by request.

If price made the decisive contribution, review the payment terms the gateway currently returns and your unit economics. If input compatibility removed the listing, correct the declared schema or decide that the request is outside your endpoint's scope. If measured latency or success rate moved the ranking, investigate the calls behind that operating signal. If a dimension was omitted, wait for sufficient observations rather than treating the omission as a measured failure.

This keeps provider action tied to evidence. It also prevents optimization for a marketplace-wide vanity number that does not exist. The relevant score belongs to a particular comparison, and the relevant improvement depends on the contribution that changed its result.

Where Apiosk fits

`GET /v1/compare?candidates={id},{id}` returns price, measured latency, measured success rate and input compatibility side by side. Each response includes the active weights and every candidate's contribution per dimension. Unmeasured dimensions are dropped and named rather than scored zero.

`GET /v1/decide?candidates={id},{id}` then returns the selected provider, the rule that picked it, rejected candidates with the exact constraints that removed them and the ordered runners-up. The same flow is available over MCP through `apiosk_compare` and `apiosk_decide`.

For providers, Apiosk is the comparison layer between a declared capability and an agent purchase. It does not claim to measure result quality or provider terms. It makes the measurements it does have inspectable, keeps hard constraints separate from ranking and returns enough scoring detail for the buyer or provider to check the arithmetic. To enter that reviewed candidate set, list your API with its capability and current input requirements.