Warmly Technical Documentation: REST API

The same three tools are exposed as a REST API for systems that don't speak MCP. Auth is per-org API key, not OAuth. Base URL: https://opps-api.getwarmly.com/api.

Run a tool by POSTing to /agent-tools/execute with Authorization: Bearer $WARMLY_API_KEY and a JSON body containing toolName, organizationId, and input. Example body: { "toolName": "list_warm_visitors", "organizationId": "<your-org-id>", "input": { "take": 25, "timeWindow": "past_day" } }

The four endpoints:

• POST /agent-tools/execute — Run a tool. Returns inline for sync tools; for async tools, poll executions/:id.

• GET /agent-tools/executions/:id — Look up one past run by id. Returns input, output, status, timing.

• GET /agent-tools/executions — List past runs. Filter by toolName, status, externalRef, or date range.

• GET /agent-tools/tools — List the tools your org has access to, with each tool's input schema.

Two optional fields on execute worth knowing. reasoning is a free-text note describing why you called the tool — stored for audit. externalRef is your own reference id (e.g. a request id from your system) — useful for searching runs later.

A request that hit the API correctly always responds with 202, even when the tool itself failed. To know whether the tool succeeded, check status and output.success in the response body — not the HTTP status. Tool-level failures come back as 202 with a human-readable userFacingError.

API keys are issued per organization from the Warmly admin UI — same place where you find your organizationId. Each key is tied to one org and acts on its behalf. Treat it like a password.

Async tool flow. A few tools (like sequence enrollment) run async. The initial /execute call returns immediately with status: pending or running. Poll GET /agent-tools/executions/:id until status reaches a terminal value: succeeded, failed, cancelled, or awaiting_approval. Synchronous tools skip this and return the result inline.

Tool discovery. Call GET /agent-tools/tools?organizationId=<your-org-id> to see exactly which tools your org can call. The response is an array of { name, description, isAsync, inputSchema }. The inputSchema is JSON Schema — use it to introspect what each tool accepts before you build against it. New tools show up here as we ship them.

Input limits. The input object is capped at 256 KB serialized, 1,000 total keys, 32 levels deep. reasoning is capped at 50,000 characters. Anything bigger comes back as 400.

Postman collection here.

Here's a video on how to create an API key in Warmly: