Discover and run tools

Browse Tools or search with POST /apis/v1/discover. Use public IDs such as exa/contents; do not use internal provider namespaces. Discovery and inspection are free.

curl https://keepbal.com/apis/v1/discover \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"exa"}'

Example discovery result (excerpt). Carry publicId unchanged through inspect and run:

{
  "data": [
    {
      "publicId": "exa/contents",
      "path": "exa/contents"
    }
  ]
}

Inspect returns pricing metadata and known input fields; it does not calculate an input-specific quote. Fixed tools show the per-call price. Variable tools are billed at provider price + 35%.

curl https://keepbal.com/apis/v1/inspect \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"publicId":"exa/contents"}'

Run the same publicId with input.body, input.queryParams, and input.pathParams. Supply the fields required by the selected tool; unused buckets can be empty.

curl https://keepbal.com/apis/v1/run \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"publicId":"exa/contents","input":{"body":{"urls":["https://example.com"],"text":true},"queryParams":{},"pathParams":{}},"max_cost_usd":"0.10"}'

Catalog tool spend caps: REST top-level max_cost_usd, MCP input.max_cost_usd, or the X-KeepBal-Max-Cost-USD header. Caps must cover the estimate and fit your available balance; they persist through async completion. Costs above the cap fail without charge. Some variable tools require a cap or quantity.

A direct public tool URL accepts the tool JSON body; it does not require a provider/endpoint/input envelope.

curl https://keepbal.com/apis/v1/exa/contents \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"urls":["https://example.com"],"text":true}'

MCP uses search_tools, inspect_tool, run_tool and get_run. Inspect first; run_tool takes tool and input. For pending results use get_run with run_id instead of starting another execution.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run_tool",
    "arguments": {
      "tool": "exa/contents",
      "input": {
        "body": {
          "urls": [
            "https://example.com"
          ],
          "text": true
        },
        "queryParams": {},
        "pathParams": {},
        "max_cost_usd": "0.10"
      }
    }
  }
}

REST may return downloads or streams when the selected tool supports them; check Content-Type and the tool schema. MCP JSON results can be truncated and unsupported downloads include a do-not-retry notice. Use the documented REST result route when needed.

Exa contents · Search and extraction · MCP reference