Unreviewed API listings make discovery broader, but they do not make a provider ready to buy from. An external record can show that an endpoint may perform the job while still leaving the buyer unable to compare its offer, construct a valid request or settle a payment through the same route.
That distinction matters because discovery systems increasingly aggregate catalogs, semantic search results and machine-readable payment records. A longer result set looks useful. For an agent operating under a budget and a deadline, however, every result also needs a clear evidence state. “Found” is one state. “Reviewed and eligible for selection” is another.
Discovery proves presence, not readiness
A discovery hit proves one narrow fact: a source published enough metadata for a query to match it. The source may include a description, resource URL, input schema and payment requirements. Those fields help an agent decide whether the endpoint deserves inspection. They do not prove that the record is current or compatible with the buyer's request.
This is the gap between recall and trust. Sweeping more sources improves the chance of finding a relevant provider. It also introduces records whose ownership, units and behavior have not been checked by the comparison layer. Treating every match as equivalent would convert coverage into false confidence.
The discovery path described in how AI agents discover APIs therefore needs two outputs. One is a candidate set that can continue through the buying workflow. The other is a set of leads that expands the search without pretending the review work has happened.
A candidate ID is a capability, not a label
In Apiosk, a reviewed catalogue result carries a stable `candidate_id`. That value is more than a convenient database key. It is the handle accepted by `GET /v1/compare?candidates={id},{id}` and `GET /v1/decide?candidates={id},{id}`. Returning it says the record has the structure required by the next step.
An external hit appears separately in `external_candidates` and has no `candidate_id`. The omission prevents accidental promotion. A client cannot pass a discovery-only record into comparison and receive a score that implies measurements, input mappings or settlement support that Apiosk does not have.
Before a listing can safely receive that handle, the catalogue needs evidence for concrete fields and relationships:
- A stable provider and resource identity, so updates attach to the same offer.
- A bounded capability, so the endpoint is compared only with providers doing the same job.
- A usable input contract and mapping, so the buyer's parameters can reach the route without guessing.
- A price and charging unit that can be interpreted beside the other candidates.
- The settlement path the gateway currently returns, rather than copied payment terms that may have drifted.
- A place to record measured latency and success rate after enough proxied calls exist.
Without those pieces, assigning an ID would make the record syntactically eligible while it remains operationally unknown.
Keep advertised metadata separate from measured facts
An unreviewed record may carry detailed metadata. Detail is not the same as verification. A declared input schema can be stale. A semantic description can match the task but omit a required field. An advertised price can use a different unit from the reviewed candidates.
The comparison layer has to preserve provenance. Provider-declared fields should stay recognizable as declarations. Measurements should name what was observed. Unknown dimensions should remain unknown.
Apiosk measures price, settlement rail and input compatibility for reviewed candidates, plus latency and success rate when enough calls have been proxied. It does not measure result quality or provider terms. When a dimension has not been measured, it is dropped from the weighting and named, never scored zero. The same discipline behind transparent API scoring weights starts one step earlier: do not produce a score until the record is eligible to be scored.
This protects providers too. An external listing should not receive a poor comparative grade because the discovery source lacks evidence. Zero would describe the collector's missing data as if it described the endpoint's performance.
The boundary prevents four expensive mistakes
Mixing reviewed and unreviewed listings creates failures that are easy to misdiagnose.
- The agent selects a record whose required input is missing, then pays for a request it cannot construct.
- Two advertised prices appear side by side even though one is per request and the other uses a different charging unit.
- A provider with no observed calls receives a reliability implication it did not earn, positive or negative.
- A buyer assumes the comparison layer can settle the call, but the discovered resource has no supported route through that layer.
These are not ranking errors. They are category errors caused by giving discovery evidence the authority of reviewed evidence. A visible `external_candidates` block lets the client handle them correctly: show the leads, inspect them separately or start a provider review, but do not silently feed them into an automated decision.
The rule also keeps decision records honest. A discovery lead is not a rejected candidate, because it was never eligible for the same decision. It should not appear among ordered runners-up or be described as losing on price, latency or reliability.
What providers should do with an external hit
Being returned as an external result is useful. It proves that the provider's machine-readable language matched a buyer's task. It is a reach signal, not a trust verdict.
The next step is to make the operational contract reviewable. Keep the capability wording consistent across the API description, discovery metadata and tool manifest. Publish every required input with its type and constraints. Make the successful output boundary explicit. Keep the resource URL stable and let the live gateway response remain authoritative for payment terms.
The provider checklist in getting your API found by AI agents covers the discovery surfaces. Moving into a reviewed catalog adds the mappings and evidence needed for comparison. A provider does not need to hide the fact that measurements are still accumulating. Unmeasured is a valid state when it is named accurately.
Where Apiosk fits
`GET /v1/discover?q=…` searches the reviewed Apiosk catalogue and can also sweep external x402 sources. Reviewed results receive stable candidate IDs. External results stay in `external_candidates`; they are unreviewed, unmeasured and not settleable through Apiosk, so they cannot chain into `/v1/compare` or `/v1/decide`.
For reviewed candidates, comparison places price, measured latency, measured success rate and input compatibility side by side. Each 0–100 score is relative to that one candidate set and ships with its weights and per-dimension contributions. Decision then returns one provider, the selection rule, every rejected candidate with the exact constraint that removed it and the ordered runners-up.
If your endpoint already appears in external discovery, list your API for review. The goal is not a badge. It is a candidate record that an agent can carry from discovery into comparison and decision without changing the evidence standard halfway through the purchase.
Frequently asked questions
What is an unreviewed API listing?
An unreviewed listing is a discovery record collected from an external source without Apiosk having established its input mapping, measurement history or settlement path. It is useful as a lead, but it is not yet an eligible comparison candidate.
Why do external API results have no candidate ID?
A candidate ID is a promise that the record can move through the comparison and decision chain. External results do not receive one because Apiosk has not reviewed the evidence needed to make that promise.
Can an agent compare the advertised price of an unreviewed listing?
It may inspect the advertised payment metadata, but it cannot treat that figure as a normalized Apiosk comparison. The charging unit, input contract and settlement route must be reviewed before the offer can be compared side by side.
How does an API provider move from external discovery to the reviewed catalog?
The provider must publish a bounded capability, executable input contract, stable resource identity and current payment metadata, then enter the Apiosk listing process. Review creates the catalog record and mappings needed for a stable candidate ID.