Skip to content
Leadbase

API and agents

Use OAuth, discover current OpenAPI contracts, and recover errors across API and MCP.

Leadbase exposes one operation catalogue through the public HTTP API, MCP and the in-app assistant. The same permissions, mutation versions, billing admission and retry rules apply across these surfaces.

Start with MCP setup for an AI client, or use the HTTP API for your own integration. External access requires the workspace's applicable API entitlement as well as authorization.

Authenticate with OAuth

Use the authorization server advertised by the protected resource metadata. The public API resource is your Leadbase origin followed by /api; the MCP resource is the same origin followed by /api/mcp. Tokens are audience-bound: an MCP token cannot be reused for the HTTP API.

Resource metadata is available at /.well-known/oauth-protected-resource/api and /.well-known/oauth-protected-resource/api/mcp. A missing token returns a 401 challenge with a resource-metadata URL. Obtain a token for the intended resource through OAuth and send it in the authorization header; do not send an app session cookie or a provider API key as a substitute.

Request mcp:read for reads and mcp:write for authorized changes or metered operations. The latter also permits reads. Membership, resource permissions and plan entitlement are checked for each execution.

Discover the live contract

The endpoints below require API authorization and return a catalogue filtered by your granted scopes:

RequestResult
GET /api/v1/operationsAvailable operation IDs, versions, descriptions and effects.
GET /api/v1/operations/{id}The operation's inputSchema and outputSchema.
GET /api/v1/openapi.jsonOpenAPI 3.1 document for the available operations.
POST /api/v1/operations/{id}Execute the operation with its JSON input.

Use dotted IDs, for example sheets.get. MCP exposes corresponding names such as sheets_get. Native schemas drive the published contracts; use them for generated client types and request validation. Runtime authorization and business checks remain necessary.

Send an uncompressed application/json body; the request limit is 1 MiB. Match the exact current schema, including required fields with explicit null where allowed. Do not infer input from an older example or a tool's display name.

Read a Sheet

The JSON body for POST /api/v1/operations/sheets.get is:

json
{  "sheetId": "11111111-1111-4111-8111-111111111111"}

The ID is illustrative; use a Sheet you can access. The response contains columns and metadata, including versions. Continue with Sheet reads and edits.

Results, errors and recovery

HTTP success returns the operation's domain result. HTTP errors normally use an error object with code and message; authentication failures have their own OAuth error response. MCP capability failures set isError and return a structured code, message and status. Successful MCP content is under structuredContent.

StatusNext step
400Read the descriptor and correct input or missing retry identity.
401Complete or refresh OAuth for the correct resource.
403Check scopes, membership, Sheet rights, plan entitlement and workspace policy.
404Check the operation/resource ID and whether it is available to your authorization.
409Read current versions or inspect the identical pending/conflicting request.
413 / 415Reduce the body or send uncompressed JSON.
429Respect admission or rate limits; do not add an independent submission pool.
5xxPreserve the error code and IDs; establish the outcome before retrying paid or mutating work.

A 200 response can contain status: "failed" or not_found for a contact lookup. It does not mean that every provider works. IDEMPOTENCY_PENDING and AMBIGUOUS_OUTCOME mean you must recover the original request rather than start a new logical operation.

Each new mutation or metered request requires its own idempotencyKey. Reuse the exact key and payload only for recovery of that request. Record operation, changeset, request or run IDs returned by the relevant schema. Internal provider errors are intentionally not exposed verbatim by the public API.

See Contact discovery, Prospect search, MCP Apps and events and Credits.