Docs

Sooma gives an agent one balance and three verbs. Everything below works with a sooma_live_ key from API Keys.

Quickstart

Skill. In your agent's chat:

set up https://sooma.dev/SKILL.md

MCP. Streamable HTTP, stateless, bearer key. Claude Code:

claude mcp add --transport http sooma https://sooma.dev/mcp \ --header "Authorization: Bearer <your API key>"

API.

curl -s https://sooma.dev/v1/discover \ -H "Authorization: Bearer $SOOMA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"find email addresses for a company domain","limit":5}'

The loop

POST /v1/discover takes a plain-language query and returns up to 20 endpoints with their price. POST /v1/inspect returns one endpoint's input JSON Schema and exact rate. POST /v1/run executes it: 200 with the settled run, or 202 for async endpoints — then poll GET /v1/runs/:id. Over MCP, run waits for async endpoints itself.

Billing

Balances and costs are integer micro-dollars (1 USD = 1,000,000). The balance must cover the price before a call starts, otherwise 402 INSUFFICIENT_BALANCE. A run is debited only after the upstream answers 2xx. Provider errors (any non-2xx) and Sooma failures cost $0. PER_RESULT endpoints charge flatFee + amount × rows. A successful response with an empty payload is still charged.

Budgets

A daily budget (UTC day) and a per-call limit can be enabled in the dashboard. A call that would breach an active limit is refused with 402 BUDGET_EXCEEDED before anything runs.

Run object

{ "runId": "01J…", "provider": "hunterio", "endpoint": "/domain-search", "status": "COMPLETED", // READY | RUNNING | COMPLETED | FAILED "output": { … }, // null on a provider error "providerResponse": { "httpStatus": 200 }, "price": { "type": "PER_CALL", "amount": 0.024, "currency": "USD" }, "billing": { "calculatedCost": { "value": 24000, "unit": "MICRO_DOLLAR", "currency": "USD" }, "actualCost": { "value": 24000, "unit": "MICRO_DOLLAR", "currency": "USD" }, "reportedCost": { "value": 24000, "unit": "MICRO_DOLLAR", "currency": "USD" } }, "resultCount": 5, "createdAt": "…", "completedAt": "…" }

Errors

400 input doesn't match the schema · 401 bad key · 402 insufficient balance or budget · 404 unknown endpoint · 503 provider not configured on this instance.