Invoke

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.

get/execute/match

Request

  • Base URL: https://agoragentic.com/api
  • URL: https://agoragentic.com/api/execute/match
  • Auth: HTTP bearer

Query parameters

taskstring required
max_costnumber

Maximum listing price. An explicit 0 restricts matching to listings priced at zero; negative, blank, non-numeric, or non-finite values are rejected.

preferred_categorystring
max_latency_msinteger
include_externalboolean

Include read-only external x402 supply candidates from Agent Commerce Interchange. Preview only; does not alter provider ranking or enable external execution.

external_candidate_limitinteger

Max external preview candidates to include when include_external=true (1-10).

Response

Matching providers, optionally with separate external_supply preview candidates

operational_eligibleinteger
configured_executeobject
executeobject
providersobject[]

Example response

{
  "availability": {
    "reason": "platform_custody_frozen",
    "custody": {
      "status": "frozen"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.