---
name: sooma
description: Discover, inspect and run 925 paid third-party APIs through one balance. Use when a task needs external data or services (email finding, web search, social scraping, WHOIS, text-to-speech, …) and the user has no direct integration for it.
---

# Sooma

Sooma is one prepaid balance and three verbs. You discover a tool, inspect its input schema and price, then run it. Every run is debited from the user's Sooma balance, so always show the price before running and start with conservative limits.

## Setup

1. Ask the user for a Sooma API key (they get one at https://www.sooma.dev/app/access/api-keys). Keys start with `sooma_live_`.
2. Send it as `Authorization: Bearer <key>` on every request. Base URL: `https://www.sooma.dev`.
3. Optional: if your client supports MCP, add `https://www.sooma.dev/mcp` (Streamable HTTP, same bearer header) and use the `discover`, `inspect`, `run` tools instead of HTTP.

## The loop

### 1. discover — find candidate tools
```
POST https://www.sooma.dev/v1/discover
{"query": "find email addresses for a company domain", "limit": 5}
→ {"count": n, "results": [{"provider", "endpoint", "description", "price": {"type", "amount", "flatFee"}}]}
```

### 2. inspect — get the input schema and exact price (always do this before run)
```
POST https://www.sooma.dev/v1/inspect
{"provider": "hunterio", "endpoint": "/domain-search"}
→ {"price": {...}, "inputSchema": {JSON Schema}, "mode": "sync" | "async"}
```

### 3. run — execute
```
POST https://www.sooma.dev/v1/run
{"provider": "hunterio", "endpoint": "/domain-search", "input": {"domain": "stripe.com"}}
→ 200 {"runId", "status": "COMPLETED", "output": {...}, "billing": {"actualCost": {"value": <micro-dollars>}}}
→ 202 {"runId", "status": "RUNNING"}   (async: poll GET https://www.sooma.dev/v1/runs/<runId> every 2s until COMPLETED or FAILED)
```

## Rules

- Never guess parameters: inspect first, then build `input` from `inputSchema` (`required` is enforced; unknown fields are rejected with 400).
- Tell the user the price from inspect before running. PER_RESULT endpoints charge per returned row plus a flat fee, so set small limits (e.g. numResults: 5) unless asked otherwise.
- `status: COMPLETED` with `providerResponse.httpStatus` outside 2xx means the provider rejected the call; `output` is null and nothing was charged. Fix the input or pick another tool.
- `402 INSUFFICIENT_BALANCE` or `402 BUDGET_EXCEEDED`: stop and tell the user; they top up or raise the budget at https://www.sooma.dev/app.
- `503 PROVIDER_UNAVAILABLE`: this Sooma instance has no credential for that vendor. Choose another tool.
- Check the balance with `GET https://www.sooma.dev/v1/wallet/balance` when the user asks what a task cost or has left.
- Prefer tools the user already has (their own MCPs, keys, integrations); use Sooma for the gaps.

## Catalog right now

- **EU VIES** (`vies`): `/validate` 0.005/call
- **Frankfurter** (`frankfurter`): `/convert` 0.002/call
- **GDELT** (`gdelt`): `/news` 0.01/call
- **Hacker News** (`hackernews`): `/search` 0.002/call
- **Hunter** (`hunterio`): `/domain-search` 0.024/call, `/email-verifier` 0.012/call
- **NHTSA** (`nhtsa`): `/decode-vin` 0.005/call, `/recalls` 0.005/call
- **npm** (`npm`): `/package` 0.002/call
- **Open Library** (`openlibrary`): `/books` 0.002/call
- **OpenAlex** (`openalex`): `/papers` 0.01/call
- **SEC EDGAR** (`sec-edgar`): `/search` 0.01/call, `/filings` 0.01/call
- **TikHub** (`tikhub`): 908 endpoints — use discover, e.g. `/api/v1/tiktok/web/fetch_post_detail`, `/api/v1/tiktok/web/fetch_post_detail_v2`, `/api/v1/tiktok/web/fetch_post_ai_article` …
- **USGS Earthquakes** (`usgs`): `/earthquakes` 0.002/call
- **Wikipedia** (`wikipedia`): `/search` 0.002/call, `/summary` 0.002/call
- **World Bank** (`worldbank`): `/indicator` 0.002/call

Full list with schemas: https://www.sooma.dev/tools