# ToolsAPI

> Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key.

Source: https://cloud.gomry.com/services/toolsapi

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 with their prices; 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.

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.

```bash
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/run \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "apify",
    "endpoint": "/apidojo/tweet-scraper",
    "input": { "handle": "gomry", "limit": 20 }
  }'
```

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.

```bash
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/discover \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "scrape recent tweets from an account", "limit": 5 }'
```

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`.

```bash
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/inspect \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor": "apify", "endpoint": "/apidojo/tweet-scraper" }'
```

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.

```bash
curl -X GET https://api.cloud.gomry.com/v1/toolsapi/runs/{runId} \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY"
```

This operation is not billed.

## Request options

- `vendor` — Required for run/inspect. Catalogue vendor slug, e.g. "apify". Monid calls this `provider`; here it is `vendor`, because `provider` already means an adapter.
- `endpoint` — Required for run/inspect. The tool's path within that vendor, e.g. "/apidojo/tweet-scraper". Both halves come from `discover` or `inspect`.
- `input` — Required for run. An object matching the tool's own `inputSchema` from `inspect`. Passed through unvalidated by us — the tool rejects what it does not accept.
- `query` — Required for discover. 1–2000 characters of natural language describing the task.
- `limit` — Discover only. How many tools to return, 1–20. Values above the ceiling are clamped, not refused.
- `timeout` — Milliseconds before the catalogue call is abandoned. 1000–90000. The run route is capped at 120s server-side.

## Pricing

| Unit | Price |
| --- | --- |
| per µ$ of tool cost | 0.00015¢ |
| per lookup | 0.2¢ |

Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](https://cloud.gomry.com/docs/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](https://cloud.gomry.com/docs/authentication).