Skip to content
Leadbase

API reference and execution

Use the live OpenAPI contract, execute operations and recover interrupted requests.

The HTTP API and MCP share contracts for operations available on both surfaces. The HTTP API also exposes direct catalog and provider operations; the public MCP server offers research entry points and sheet management. Use HTTP for your application and MCP for a compatible AI client. Both enforce workspace access and billing.

Discover the contract

RequestPurpose
GET /api/v1/openapi.jsonPublic OpenAPI 3.1 document; no key required to read schemas
GET /api/v1/operationsAuthenticated operation catalog filtered for your access
GET /api/v1/operations/{id}Current input and output schemas
POST /api/v1/operations/{id}Execute with the schema-valid JSON body

HTTP operation IDs use dots, such as enrichment.start. Shared MCP tools use underscores, such as enrichment_start. MCP discovery is authoritative: converting an HTTP ID to underscores does not make an unlisted tool callable. Discover exact IDs and parameters rather than guessing from titles. Send uncompressed application/json; the request body limit is 1 MiB.

For a complete first request, see typed enrichment. Use API authentication and bulk retrieval next.

Research through HTTP or MCP

Use sheets.research (sheets_research in MCP) for a new saved list, sheets.enrich (sheets_enrich) for an existing sheet column, and enrichment.start (enrichment_start) for 1–100 independent items without a sheet. The unified enrichment endpoint supports many email and phone requests in the same batch. See the bulk contact example and MCP setup.

Run a catalog tool through HTTP

The following direct catalog operations are HTTP-only on the public integration surface. First post to /api/v1/operations/tools.list with {"query":"search"}. Select an available tool from the response and inspect its inputSchema. Then post to /api/v1/operations/tools.run:

json
{  "toolId": "ID_FROM_TOOLS_LIST",  "parameters": {},  "idempotencyKey": "catalog-task-001"}

Replace the placeholder and populate parameters with the fields required by that tool; the empty object is only a structural example. The response contains the full provider result, attempts and actual provider cost. Individual endpoints execute directly; groups run their configured waterfall. Neither path adds a research-model round. Repeating the same request with the same idempotency key returns the retained response without another provider charge.

Handle errors deliberately

StatusAction
400Correct input using the current schema
401Check key validity or OAuth token and audience
403Check membership, scopes, entitlement and workspace policy
404Verify the operation, tool or resource ID
409Inspect the original request and its retry identity
413 / 415Reduce the body or use supported JSON encoding
429Back off and respect any retry information
5xxDetermine the original request's outcome before resubmitting paid work

A transport success is not proof of a found result. Inspect domain status, error codes, values and billing state. Preserve the response's identifiers. For an ambiguous submission, reuse the same idempotency key and identical payload; changing the key can create new paid work. See troubleshooting.