Call an API
callRoute a call to the Routavo network, meter it, and return the result. Give either a provider id from discover(), or a capability and let Routavo pick using its published routing rule. Optional max_price and max_latency_ms constrain the choice. Failed calls are recorded but cost nothing.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | Instead of one call, a sequence of up to 8 steps: [{ id, capability | provider, arguments, max_price?, max_latency_ms? }]. A later step may take a value from an earlier one with { "$ref": "<step id>.output.<path>" }, e.g. { "$ref": "geo.output.results[0].lat" }. The whole plan is quoted before anything runs; with dry_run it is only quoted. Steps run in order and stop at the first failure. Each step returns its own receipt and the response carries one total. | |
| batch | No | Instead of one arguments object, up to 50 of them for the same capability or provider. Run in parallel, each with its own receipt, one total. Failed items cost nothing and do not stop the others. | |
| budget | No | A task budget: { id, max }. Spend under this id is tracked across any number of calls, plans and batches, and a call that would take it past max is refused with code "budget". { id, statement: true } returns what the budget has spent and the receipts behind it. | |
| fields | No | Return only these output paths, e.g. ["results.name", "results.lat", "results.lng"]. Saves tokens; the receipt still hashes the full answer. | |
| quorum | No | Ask 2 or 3 providers the same question and get an agreement score with every answer. Each provider is charged. Refused if fewer providers clear your constraints, so quote it first with dry_run. | |
| recipe | No | A named, published plan, e.g. "weather_for_place". Give its arguments and it runs the steps for you, quoted first, with the last step's output on top. discover() lists recipes with their inputs and estimated price. | |
| wallet | No | Your wallet address, asserted. Attributes metering and a daily cap on the free tier; it proves nothing. To pay from a balance, prove the wallet once at /api/wallet and send the key it returns as wallet_key or as Authorization: Bearer rw_... | |
| dry_run | No | Quote only: which provider would be chosen, at what price, with what latency, and why. Nothing is called, charged or counted. | |
| payment | No | Pay this one call with x402: { rail: "x402", payload: <PaymentPayload> }, an EIP-3009 authorization to the pay-to address for at least the price, signed by your wallet. The requirements to sign are in discover() and in any payment_required error. A facilitator verifies and settles it; the receipt carries the transaction. | |
| failover | No | Default true when routing by capability: if the chosen provider fails, the next eligible one is tried and only the one that answered is charged. Set false to fail fast. | |
| provider | No | Provider id, e.g. "open-meteo.geocode". Omit to route by capability. | |
| arguments | No | Arguments in the capability contract shape from discover(). Learn geocode once; every provider behind it takes the same input and returns the same output. | |
| max_price | No | Do not route above this price per call, e.g. "0.0030" | |
| max_total | No | For a plan: do not run if the quoted total exceeds this, e.g. "0.0100". | |
| capability | No | Capability to route on, e.g. "geocode". Ignored when provider is given. | |
| wallet_key | No | A wallet key (rw_...) from /api/wallet. Proves the wallet, and calls are paid from its deposited USDC balance. Prefer sending it as the Authorization: Bearer header. | |
| max_latency_ms | No | Do not route to a provider slower than this p50 | |
| idempotency_key | No | Your own id for this call, up to 64 characters. A retry with the same key within 24 hours returns the same result and receipt and is never charged again. The output is kept for those 24 hours only because you asked for replay. |