Explainable API Routing Decisions for Agents

Explainable API routing decisions let an operator answer three questions in one read: which provider won, why it won, and what can replace it. If the response only returns a provider name or a score, the route may be automated, but it is not yet operable.

The missing piece is usually not more reasoning text. It is a decision record with enough structure to preserve the rule, the exclusions, and the fallback order. That record lets a person approve the route, overrule it, or investigate it without reopening discovery and rebuilding the comparison.

Explain the applied policy, not an agent's thoughts

An agent can interpret a task and turn it into requirements. The final route should still come from a rule that another system can apply again.

This separates two different kinds of explanation. A narrative such as “provider A looked suitable” describes an impression. An applied policy states that the candidate passed every hard constraint and ranked first under `optimize_for=latency`. The second explanation can be checked against the same inputs. The first cannot.

For API routing, explainability should therefore mean observable decision evidence rather than a transcript of hidden reasoning. The useful evidence includes the requirements supplied, the candidates evaluated, the rule applied, and the resulting order. This is the same boundary that makes paid API comparison at decision time useful: the arithmetic has to travel with the result.

A deterministic rule does not mean every buying policy must be simple. It means the route is reproducible. If requirements or measurements change, the result may change. If they do not, the same rule should not quietly pick another provider.

Put the whole decision in one response

An operator-readable response needs more than a winner. It should carry the complete decision surface:

• The selected provider and its stable candidate identifier.
• The routing rule, including whether price, latency, reliability, or a balanced weighting determined the order.
• The hard requirements applied, such as `max_price`, `max_latency_ms`, `min_reliability`, settlement preference, and required input compatibility.
• Every candidate removed before ranking, paired with the exact constraint it failed.
• The eligible runners-up in order, with the measurements and score contributions needed to inspect that order.
• Any dimension that was unavailable and therefore dropped from the weighting.
• A decision identifier that can connect the route to a later provider call or override record.

These fields reduce the number of systems an operator has to consult. The response should not require a search through gateway logs to learn that one candidate exceeded the price ceiling and another lacked a required input. Nor should it require rerunning the comparison to find the next eligible provider.

The 0–100 score is relative to the candidates in that one comparison. It is never a permanent provider grade. The weights and each candidate's contribution per dimension need to accompany it. Otherwise a score compresses the decision while discarding the evidence required to challenge it.

Keep exclusions separate from runners-up

Rejected candidates and runners-up answer different operational questions.

A rejected candidate failed a hard requirement. It might exceed `max_price`, miss `min_reliability`, fail `require_all_inputs`, or conflict with the requested settlement mode. It should not appear as a convenient fallback, because fallback does not remove the original requirement.

A runner-up passed the hard requirements but ranked below the winner under the chosen optimization rule. It is eligible. That makes it a real alternative when an operator knows something the routing layer does not measure.

This distinction matters because Apiosk does not measure result quality or provider terms. An operator may have current evidence about either and choose the second-ranked eligible provider. That does not make the automated result inexplicable or wrong. It means the human introduced information outside the measured dimensions. A clean override record should say so.

The distinction also prevents unsafe promotion of discovery-only results. Apiosk's discovery sweep can return external x402 sources in a separate `external_candidates` block. Those entries are unreviewed, unmeasured, have no `candidate_id`, and cannot move into comparison, decision, or settlement. They are leads to investigate, not runners-up to call.

Make an override a recorded event

An override should add a record, not rewrite history.

Keep the original selected provider, policy rule, constraints, and candidate order. Then record the operator's chosen runner-up and the reason for the change. This preserves two facts: what the routing policy returned and what was actually executed.

Useful override reasons are concrete. The operator may know that a provider is under maintenance, that its terms are unsuitable for this workload, or that recent output did not meet an internal quality review. Those are legitimate reasons, but they should not be disguised as measurements the router made.

An override flow can stay short:

• Read the winner, rule, exclusions, and ordered runners-up.
• Confirm that the replacement is eligible under the original hard constraints.
• Record the replacement candidate and a specific override reason.
• Keep the original decision identifier on the executed call.
• Review repeated overrides as a possible routing-policy or listing-data problem.

The last step turns overrides into useful operational feedback. If people repeatedly replace a latency-optimized winner because of a factor the router cannot measure, the answer may be a different policy or an explicit approval step. It is not a hidden adjustment to the score.

Treat fallback as a new decision when facts change

An ordered runner-up makes an immediate override cheap. It does not make every later fallback automatic.

If the selected provider fails before execution and the requirements and measurements remain valid, the next eligible candidate may be usable under the same decision. If a payment requirement changes, the latency ceiling changes, or fresh measurements alter eligibility, the old order no longer answers the current question. Run the decision again with the new facts.

This is where paid API fallback routing and explainable selection meet. A fallback record should distinguish an execution failure from a policy rejection, preserve the original route, and say whether the replacement came from the existing runners-up or from a fresh decision.

That boundary prevents a fallback chain from becoming an unexamined allowlist. An ordered list is only valid under the requirements and candidate evidence that produced it.

Store decisions separately from provider calls

The provider that receives a request can log the call, but it cannot log the alternatives it never saw. The agent's general trace may show tool activity, yet still omit the candidate set and the exact elimination rules.

Store the routing decision as its own operational object. Connect it to the executed request with a stable identifier. This gives support and operations a compact audit trail without requiring private prompt content or a model's hidden reasoning.

The record also gives API providers clearer feedback. A provider that loses because it exceeded a stated latency ceiling has an actionable reason. A provider that was never eligible because its input schema did not match has a different problem. Capability-based discovery handles that earlier boundary before offers are ranked.

Where Apiosk fits

Apiosk turns the discover, compare, and decide steps into separate callable operations. `GET /v1/decide?candidates={id},{id}` returns one provider, the rule that picked it, every rejected candidate with the exact constraint that removed it, and the runners-up in order. The same requirements can travel from discovery through comparison to decision, so the final record answers the question the buyer originally asked.

`POST /v1/decisions` records which provider was chosen and which alternatives were rejected. It is free and unauthenticated, keeping the recording step separate from the paid provider call. For MCP clients, the equivalent selection tool is `apiosk_decide`.

If you operate an endpoint, explainable routing makes losses as useful as wins. The record shows whether you missed a hard requirement or ranked behind another eligible offer. You can list your API on Apiosk so agents can discover it, compare current measurable terms, and receive a route that an operator can inspect before traffic reaches your endpoint.