API Input Compatibility Mapping for Agent Buyers

API input compatibility mapping turns one agent request into a request each eligible provider can actually accept. Without that mapping, two endpoints that advertise the same job may still fail on different names, types, formats, or required fields after the buyer has already selected one.

Consider a company lookup. The agent has a domain. One provider expects `domain`, another expects `website_url`, and a third requires both `company_name` and `country_code`. The first rename may be mechanical. The third provider is not callable from the available input. A comparison layer has to expose that difference before price, latency, or reliability can influence the choice.

Start with a canonical buyer request

A mapping needs a stable left-hand side. That should be the request the buyer can supply for the capability, not the request shape of whichever provider was integrated first.

For a bounded job, define the canonical fields in task language. Record enough detail to validate a request without calling a provider:

• field name and plain-language meaning;
• required or optional status;
• JSON type and accepted formats;
• allowed values or constraints;
• object and array structure;
• unit, timezone, locale, or encoding where relevant;
• whether an omitted field differs from an explicit `null`;
• one valid example that exercises the normal path.

This is a narrower step than capability-based API discovery. Discovery groups endpoints that claim to perform the same bounded job. The canonical request tests whether those candidates can perform that job with the inputs this buyer has now.

Do not use a provider-specific name such as `website_url` as the canonical meaning unless the capability truly requires a URL. If a bare domain is sufficient for the job, the canonical field should say so. Otherwise every later mapping inherits an assumption made by one seller.

Map meaning before names

Parameter renaming is the easiest case, but matching by name alone is unsafe. `location` might mean a postal address, a latitude-longitude pair, a country code, or free text. Identical labels can carry different contracts.

For every provider field, the mapping should state the canonical source, the provider target, and the operation between them. An identity mapping copies the value. A rename changes only the key. A structural mapping may place a field inside an object or split one canonical value into several provider fields. A normalization may change case, date notation, or a unit without changing meaning.

Transformations need explicit boundaries. Converting metres to kilometres is deterministic. Inferring a missing jurisdiction from an IP address adds information the buyer did not provide and can change the result. That is not a harmless input mapping. It should be declared as enrichment or rejected when the job requires the original value.

Defaults need the same discipline. A schema default can document expected behaviour, but it does not necessarily insert a missing value into a request. The mapping should say whether the provider applies the default, the routing layer supplies it, or the field remains absent. Silent default insertion makes failed comparisons difficult to reproduce.

Required fields create hard eligibility rules

Compatibility is not an average. If the provider requires a field that cannot be derived safely from the canonical request, the candidate is ineligible for that call.

The comparison record should distinguish at least four states:

• mapped, where the available value reaches a compatible provider field;
• transformed, where a named deterministic operation produces the provider value;
• optional and omitted, where the provider contract permits absence;
• missing required input, where the request cannot be constructed.

That final state should behave as a constraint, not as a weak score. An endpoint that cannot be called should not rank above a compatible endpoint because it is cheaper. When `require_all_inputs` is carried through Apiosk discovery, comparison, and decision, a missing required mapping can remove the candidate explicitly.

The distinction also improves failure handling. The agent can ask for a missing country code, revise the task, or choose a provider that accepts the existing domain. It does not have to learn about the mismatch from a paid request that returns a validation error.

Test mappings against real request shapes

A mapping document is only useful if it survives examples. Validate the canonical request first, construct each provider request, then validate that result against the provider's current schema.

Tests should cover the normal request and the edges that commonly break substitution: omitted optional fields, explicit `null`, empty arrays, nested objects, enum values, numeric boundaries, date formats, and additional properties. For arrays, record whether order and duplicates carry meaning. For strings, distinguish a format annotation from a transformation the provider actually performs.

OpenAPI descriptions and MCP tool schemas provide useful source contracts. An MCP tool's `inputSchema`, for example, defines the expected arguments as JSON Schema. Those schemas describe individual tools; they do not establish that two tools accept the same buyer request. The compatibility mapping is the relation between them.

Version the tests with the provider schema. A provider can keep the same route while making an optional field required or narrowing an accepted enum. That change may leave discovery intact but invalidate the mapping. Providers should review their listing whenever an input contract changes, just as they should review API endpoint versioning for agent traffic when a new version affects the commercial request.

Keep compatibility separate from ranking

Input mapping answers whether a candidate can receive this request without changing its intent. Ranking answers which eligible candidate best matches the buyer's priorities. Combining them hides why a provider lost.

`GET /v1/compare?candidates={id},{id}` places input compatibility beside price, settlement rail, and sufficiently measured latency and success rate. The 0–100 score is relative to that candidate set. The response carries the weights and each candidate's contribution, so the buyer can recompute it. Dimensions not measured for a candidate are dropped from the weighting and named, never scored zero.

A required-input failure is different. It removes the provider under the stated constraint. It should appear as the exact reason, not as an unexplained reduction in a blended score. This keeps comparison at agent decision time auditable: compatible providers can be ranked, while uncallable providers are excluded.

Input compatibility also does not prove output equivalence. Apiosk does not measure result quality or provider terms. Providers must publish what a successful response contains, and buyers must decide whether that output contract satisfies the task. A precise request mapping cannot repair a result that lacks required data.

Publish enough detail to be substituted

If you operate an endpoint, publish a complete input schema and a working request. Mark required fields as required. Describe formats, units, allowed values, nesting, and omission behaviour. Keep the listing aligned with the endpoint that receives paid traffic.

Avoid prose-only instructions such as “send a company identifier.” Name which identifiers are accepted and what each one means. If two fields are alternatives, make that relationship machine-readable. If one field becomes mandatory only when another has a particular value, state the condition. These details determine whether a comparison layer can construct a valid mapping or must exclude the candidate.

You do not need to adopt the same parameter names as every competitor. You do need to make the transformation into your contract explicit and testable. That is what lets your endpoint enter a substitutable set without hiding its real requirements.

Where Apiosk fits

Apiosk keeps the compatibility check inside the buyer's decision chain. `GET /v1/discover?q=…` returns reviewed catalogue candidates with stable `candidate_id` values. `/v1/compare` evaluates those candidates against the shared requirements, including input compatibility. `/v1/decide` returns one provider, the rule that selected it, each rejected candidate with the exact constraint that removed it, and ordered runners-up.

External x402 discoveries remain in a separate `external_candidates` block. They have no `candidate_id`, are unreviewed and unmeasured, and cannot enter comparison, decision, or settlement through Apiosk. A published schema can make an external endpoint findable, but it does not make that endpoint reviewed or mapped.

For a provider, the practical next step is to publish the request contract that a mapping can validate: required fields, types, formats, constraints, and a working example. You can list your API when that contract is ready. API input compatibility mapping then gives the buyer a concrete answer to the question that comes before every ranking: can this provider accept the request I already have?