Capability-Based API Discovery for Agent Buyers

Capability-based API discovery starts with the job an agent needs completed, not the vendor it already knows. That change sounds small, but it determines whether a search returns one familiar product or a usable set of providers that can compete for the same call.

A provider name is an address. A capability is a promise about work: verify one tax number, extract fields from one invoice, enrich one company record, or translate one document. Agents arrive with that kind of task. If your endpoint is indexed only under your company name or broad category, the agent has to know you before it can find you.

Vendor directories answer the wrong first question

A conventional API directory is organized around publishers, products, and routes. That structure helps a developer who already has a shortlist. It is weaker when an agent must answer, “What can complete this task within my requirements?”

Capability-based discovery reverses the lookup. The agent describes the work. The discovery layer resolves that description to a normalized capability, then returns every eligible provider attached to it. The provider remains visible, but it is no longer the organizing principle.

This is narrower than the complete path described in how AI agents discover APIs. That path covers the documents and surfaces a crawler reads. Capability grouping deals with what happens after those documents have been ingested: which listings belong in the same candidate set.

The distinction matters because a long result list is not necessarily a market. Ten “data APIs” may perform ten different jobs. Two endpoints from unrelated vendors may be true alternatives if both return the same bounded company profile from the same business-domain input.

A capability needs an operational boundary

A category such as enrichment, search, or compliance is too broad to support a decision. A capability has to be specific enough that one successful call has a recognizable contract.

The discovery record should let a buyer identify:

• the job performed, written in task language rather than product language;
• the required and optional inputs, including types and working examples;
• the successful output and the limits placed on that result;
• the charging unit, such as one request, page, record, or successful result;
• the current payment terms returned by the live gateway;
• the conditions that make a candidate ineligible before comparison.

These fields create the boundary around the job. “Company intelligence” does not. “Return one verified company profile for one submitted domain” is closer because the input, unit, and output can all be tested.

This is also why a machine-readable API payment catalog has to describe more than price. A price without a unit cannot be compared. A unit without an output boundary does not tell the buyer whether two offers buy the same thing.

Substitutability is earned through input mapping

Grouping two providers under one capability is only the start. The offers become substitutable when the discovery layer can map the buyer's request into both providers without changing the intended job.

One endpoint may accept `domain`; another may require `website_url`. That difference is mechanical. A published mapping can resolve it. A deeper difference is not mechanical. If one provider requires a legal company name and jurisdiction while another works from a domain alone, the same buyer input may not make both callable.

The candidate set therefore needs an input-compatibility check. Apiosk can reuse shared requirements such as `require_all_inputs` throughout discovery, comparison, and decision. A candidate missing required input coverage should be removed explicitly, not left in the ranking with an attractive price.

Output boundaries deserve the same care. Two providers may both call their result a company profile while returning materially different fields. Apiosk does not measure result quality, so it does not turn that difference into an invented score. Providers must publish what a successful response contains, and the buyer must decide whether that contract is sufficient.

Discovery and comparison are separate operations

Capability matching answers whether a provider belongs in the set. Comparison answers how the eligible providers differ. Combining those steps hides important exclusions.

In Apiosk, `GET /v1/discover?q=…` returns reviewed catalogue candidates with stable `candidate_id` values. Those identifiers can be passed to `GET /v1/compare?candidates={id},{id}`. The comparison places price, settlement rail, input compatibility, and sufficiently measured latency and success rate side by side.

The 0–100 score is relative only to the candidates in that comparison. The response includes its weights and each provider's contribution. If a dimension has not been measured for a candidate, Apiosk drops that dimension from the weighting and names the omission. It is not scored zero. Result quality and provider terms are not measured anywhere.

Keeping discovery separate also makes rejection legible. An agent should be able to distinguish “this provider cannot perform the job with these inputs” from “this compatible provider ranked second on the selected optimization rule.” The first is a capability constraint. The second is a buying decision.

External discovery expands coverage without faking equivalence

A discovery system can search beyond its reviewed catalogue, but more coverage does not make every hit comparable. Apiosk also sweeps external x402 sources. Those results appear in a separate `external_candidates` block with no `candidate_id`.

That separation is deliberate. External hits are unreviewed, unmeasured, and not settleable through Apiosk. They cannot chain into `/v1/compare` or `/v1/decide`. Mixing them into the reviewed candidate set would imply an input mapping, measurement history, and settlement path that do not exist.

For a provider, this creates two useful states. A machine-readable document can make an endpoint findable across the wider web. A reviewed listing can make it eligible for comparison and selection. Paid API discovery for agents needs both reach and a trustworthy boundary between what was merely found and what can actually be bought through the comparison layer.

Publish the job in every machine-readable surface

The same capability wording should survive across your discovery document, API description, catalogue listing, and tool manifest. Exact formatting may differ, but the job, input contract, output boundary, and payment posture should not contradict one another.

For MCP, the tool name, description, and input schema give a model the basic invocation surface. Over the Apiosk MCP server, the same discovery chain is exposed as `apiosk_discover`, `apiosk_compare`, and `apiosk_decide`. The transport changes; the requirement to group and filter providers by the work does not.

Review this metadata whenever an input, response field, charging unit, or live payment term changes. Discovery systems often work from cached documents. A stale capability record can keep an endpoint visible while making the first real call fail.

Where Apiosk fits

Apiosk is the decision layer between an agent's task and the provider endpoint that receives the call. `GET /v1/capabilities` exposes the jobs in the catalogue. `/v1/capabilities/{slug}` returns the candidates for one job, cheapest first. Discovery then builds the candidate set, comparison measures the eligible offers, and decision returns one provider, the rule that selected it, every constraint that removed another candidate, and the runners-up in order.

For providers, the immediate work is concrete: define one bounded job, publish its input and output contract, and keep the live payment terms aligned with the listing. You can list your API once those fields are ready. Capability-based discovery gives the endpoint a place in the right set; clear compatibility and measured delivery determine whether it stays there when an agent decides.