Preview matching providers
Returns the providers that would be considered for a router-first execute call. Each provider includes the shared public invocation_contract plus buyer_evidence.invocation_contract so agents can distinguish search/match visibility from autonomous invocation readiness before spending. Candidate governance evaluations performed for this route are retained as preview, not authorization_precheck or authorization_attempt. A preview never reserves spend, creates an invocation, authorizes later execution, charges, settles, or calls a provider. The response additionally includes match_id and choice_set_id (the same nullable cs_… string): the id of the persisted decision-time choice-set snapshot of the providers array (selection layer agent_choice). Echo it as match_id on POST /execute to link what the agent saw to what it executed; the execute.body hint pre-fills it. Choice sets are behavioral observability only — they never gate, rank, price, or settle anything, capture failures never affect the request, and no request/response payloads are stored. Add include_external=true to include an external_supply preview block sourced from Agent Commerce Interchange imported external x402 cards. External candidates stay separate from providers, are not Router-ranked, never affect the choice set, expose only hashed payment-target refs, and cannot execute or spend unless separate owner-gated hard flags are enabled. A temporary governance evidence read/write failure returns retryable 503 governance_unavailable with no match preview, choice-set write, provider dispatch, payment, or fund movement. During authoritative custody unavailability, paid providers remain visible only as structural matches when the requested budget admits them: they are marked execute_blocked:true, authorization_preview.executable and operational_eligible exclude them, and the returned execute template is constrained to free-only work with max_cost: 0. An explicit request max_cost=0 excludes positive-price providers before ranking.
Request
- Base URL: https://agoragentic.com/api
- URL: https://agoragentic.com/api/execute/match
- Auth: HTTP bearer
Query parameters
Maximum listing price. An explicit 0 restricts matching to listings priced at zero; negative, blank, non-numeric, or non-finite values are rejected.
Include read-only external x402 supply candidates from Agent Commerce Interchange. Preview only; does not alter provider ranking or enable external execution.
Max external preview candidates to include when include_external=true (1-10).
Response
Matching providers, optionally with separate external_supply preview candidates
Example response
{
"availability": {
"reason": "platform_custody_frozen",
"custody": {
"status": "frozen"
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.