Skip to main content
ToolsAPI is one key over someone else’s whole catalogue. Describe a task to POST /v1/toolsapi/discover and it returns the tools that can do it; POST /v1/toolsapi/run executes one and returns its output. You never sign up with the vendor, hold their key, or reconcile their invoice.

​
Overview

Billing is the vendor’s cost plus our margin, metered in micro-dollars rather than in calls, because tools here range over four orders of magnitude in price — billing every call the same would either overcharge the cheap ones or give away the expensive ones. The meteredMicroUsd field in each response is exactly what went on your invoice. Discovery and inspection are billed as a flat lookup; polling a run is not billed at all. A run has two independent outcomes and reading them as one is the most common mistake. status says whether the run completed; upstreamStatus says what the tool itself answered. A succeeded run carrying 404 is normal and means the tool looked and found nothing — that is an answer, not an error, and retrying it just pays a second vendor for the same fact. Two failures, and the difference is whether retrying can help. 404 tool_not_runnable means the catalogue refused this vendor / endpoint / input — an unchanged retry will be refused again, so check the address against discover and the input against inspect. 502 run_failed means the catalogue could not be reached or did not answer, and retrying is exactly right. Neither is billed. ⚠️ A tool’s advertised price is usually unknown, and discover says so rather than guessing. price.amountMicroUsd is null when the catalogue published no rate — which today is most of them — and null means UNKNOWN, not free. What a run cost is never a guess: meteredMicroUsd is the amount the vendor actually charged, returned with the result and identical to the invoice line. Read the price as a hint and the metered amount as the fact. What it does not do: it does not translate your input between tools. input is passed to the tool unchanged and must match the schema inspect returns, so two tools that do the same job with different argument names are two different calls. It also does not guarantee a price in advance for PER_RESULT tools — cost depends on rows returned, which is unknowable before the call, so the real ceiling is your project’s monthly budget cap rather than a per-call estimate.

​
Endpoints

POST /v1/toolsapi/run — Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key.
The response reports meteredMicroUsd — the quantity you were metered for this call. POST /v1/toolsapi/discover — Describe a task in words and get back the tools that can do it, ranked, with prices.
The response reports lookups — the quantity you were metered for this call. POST /v1/toolsapi/inspect — One tool’s input schema, price and docs — what you need to build a valid input.
The response reports lookups — the quantity you were metered for this call. GET /v1/toolsapi/runs/{runId} — Poll a run that came back RUNNING. Not billed — you already paid for the run.
This operation is not billed.

​
Request options

​
Pricing

Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see Billing.

​
Authentication

Send a key as a bearer token. This service’s operations require the toolsapi:read and toolsapi:run scopes, granted independently — and the project must have ToolsAPI enabled. See Authentication.