Find (and optionally pay) the best service for a need
route_by_intentGiven a plain-language description of what you need, find, and optionally pay in the same call, the single best payable catalog service, so you do not have to pick among listings yourself. Use it instead of search_services when you want the right service for a task rather than a list to browse: it ranks candidates on Nevermined's own relevance and quality signals (deterministic; no model reads the merchant listings), applies a fail-closed payability gate (listed, healthy, moderated, x402/mpp, not flagged unpayable), and returns the winner as chosen (with its opaque invoke handle, never a raw host) plus a ranked shortlist and the rankingSource used (semantic or lexical). With autoPay:false (the default) it returns the pick only and charges nothing; the next step is normally get_service on chosen.slug, then pay_service with the endpoint you need. With autoPay:true it also pays the winner through the same path as pay_service and returns the upstream call in result: result.status and result.body are the vendor's answer, and result.paid: true means a payment was attempted, not that it settled, so read result.payment.status (Settled, Issued or Failed). autoPay calls the winner at its base URL plus any path you pass, and you only learn the winner from this call, so it suits single-endpoint services; a multi-endpoint winner typically answers 404 at its base URL. autoPay requires requestId; an API-key caller must also pass delegationId, while an OAuth-connected caller spends from the grant it approved and needs none. Outcomes: no listed, payable match → {"status":"no_fundable_match"} (broaden the intent or filters; nothing charged), never a wrong pick; missing_autopay_fields (nothing charged); on autoPay, payment_indeterminate (check list_payments, and retry only with the same requestId) and already_paid (this requestId was already paid, see paymentId; nothing new billed). Every pick and each of these outcomes carries an instructions string with the next step; a payment the Router declines on autoPay comes back as a tool error carrying the API's message. Requires your Nevermined API key on the Authorization header.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body for the paid call (autoPay only). | |
| path | No | Subpath appended to the winner when paying (autoPay only). | |
| limit | No | Shortlist size to return (1–20, default 5). | |
| intent | Yes | Plain-language description of the service you need (e.g. "translate English to German"). | |
| method | No | HTTP method for the paid call (autoPay only). | |
| search | No | Query string (no leading ?) for the paid call (autoPay only). | |
| autoPay | No | When true, also pay and relay the winner in the same call (same path as pay_service); requires requestId, plus delegationId when you authenticate with an API key. Default false → return the pick only, no charge. | |
| filters | No | Optional structured narrowing; all fields optional. | |
| headers | No | Extra headers for the paid call (autoPay only). | |
| requestId | No | Idempotency key — REQUIRED when autoPay is true. | |
| delegationId | No | Delegation to charge on autoPay. Required when you authenticate with an API key; an OAuth-connected caller spends from the grant it approved, so it can omit this (a value there does not choose the delegation). | |
| maxTotalCents | No | Refuse a paid quote above this (fee-inclusive), before purchase (autoPay only). | |
| credentialHeader | No | Header the Router should carry the minted payment credential in on the paid hop (autoPay only). Send it only when the winning service needs its own auth AND a payment credential (e.g. "Payment"). Ignored when autoPay is false. |