route_by_intent

io.github.nevermined-io/catalog · Verify this server

Given 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`; every shortlist item carries a closed `matchReason`, `gateReason`, per-item `rankingSource`, and one scale-specific score. 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.