The Operelio API and MCP server

Operelio's API runs the same trails, leads, tools and CRM pushes as the app from your code. Its MCP server lets an AI assistant like Claude or ChatGPT work with your trails, leads, tools, CRM pushes and Bridgeant. Both follow your plan's own rules.

Get started free Read the quickstart

Asks before changing your data
Read-only API keys
Signed webhooks

Your codeCalls the API with a key

GET /api/v1/trailsPro and Agency

Your AI assistantSigns in to the MCP server

Which leads are held?

Every plan

Your endpointGets a webhook when it happens

lead.heldPro and Agency

Your Operelio workspaceWhat the app runs, from outside it

TrailsInbound leads, on
Leads17 held
ToolsDeduplicate and 16 more
Do Not Contact2,184 entries
CRM pushHubSpot connected

Same checks, limits and admin rights as the app.

Where a push lands

HubSpot
Salesforce
Pipedrive

APIFor your own codePro and Agency
MCP serverFor Claude, ChatGPT and other assistantsEvery plan
WebhooksFor hearing back as it happensPro and Agency

The API

Call the API from your own code

The API lets your own code read and change what you see in the app: trails, routing teams, leads, files, workflows, Do Not Contact, CRM pushes and Bridgeant.

Held leads on one trailGET

curl -G https://operelio.com/api/v1/leads \  -d state=held -d trail=4f2a… \  -H "Authorization: Bearer op_7Kq2xV…"

Reply200

{  "data": [    {      "id": "c81e…",      "state": "held",      "score": null,      "heldReason": "missing_field"    },    …  ],  "nextCursor": "…"}

Make a keyOn the API keys page in Operelio. Pick read only or read and write. A key that changes things must be made by an admin.
Send it with each requestAs a Bearer token, to the base URL.https://operelio.com/api/v1Authorization: Bearer op_…
Stay inside your limits1,000 calls a month on Pro, 5,000 on Agency. Only writes, runs and Bridgeant questions that use a message count. Reads don't. Each key can make 60 requests a minute.

API quickstart Keys and access

The API keys page in Operelio: two keys with their last use and request counts, and two webhook endpoints — Your keys and webhook endpoints, on the API keys page in Operelio.

Every endpoint

Counts toward your monthly calls. The rest are reads and don't.

Trails and runs

GET/trailsEvery trail, its state and held leads
GET/trails/{id}One trail, with its source, CRM and routing
GET/trails/{id}/runsIts runs, newest first
GET/runs/{id}One run, with where each row went and why
POST/trails/{id}/pausePause a trailCounts toward your monthly calls.
POST/trails/{id}/resumeSwitch it back on, after the same checks as the buttonCounts toward your monthly calls.
GET/trails/{id}/routingIts rules, teams and who is next
PUT/trails/{id}/routing/teams/{groupId}/membersChange who is on a teamCounts toward your monthly calls.

Leads

GET/leadsLeads in review, held, or all
GET/leads/{id}One lead and its timeline

Do Not Contact

GET/dnc/entriesSearch your list
POST/dnc/entriesAdd up to 500 at onceCounts toward your monthly calls.
DELETE/dnc/entries/{id}Remove oneCounts toward your monthly calls.
POST/dnc/checkCheck up to 100 values

Files, tools and workflows

POST/uploadsUpload a CSV or Excel fileCounts toward your monthly calls.
POST/jobsRun a tool on itCounts toward your monthly calls.
POST/jobs/batchRun a tool on many files at once (Agency)Counts toward your monthly calls.
GET/jobs/{id}Check until it has finished
GET/jobs/batch/{id}Check a batch's progress
GET/jobs/batch/{id}/downloadDownload a batch as one ZIP
GET/files/{id}/downloadDownload the result
GET/workflowsYour saved workflows
POST/workflows/runRun one by its nameCounts toward your monthly calls.

CRM

GET/crm/connectionsThe CRMs you connected in the app
POST/jobs/{id}/pushPush a finished file to your CRMCounts toward your monthly calls.
GET/jobs/{id}/pushWhat the push created and updated
GET/crm/ownersYour CRM's users
GET/mappingsYour saved column mappings
GET/mappings/{id}One saved mapping

Reports

GET/analytics/{view}The numbers on the Analytics tab
GET/activityEverything that ran, and who ran it

Bridgeant

POST/bridgeant/askAsk Bridgeant a question, charged as a chat turnCounts toward your monthly calls.
POST/bridgeant/actions/{id}/confirmRun what it offeredCounts toward your monthly calls.

Every path starts with https://operelio.com/api/v1. Lists come 25 at a time, up to 100, with a cursor for the next page. See each one's fields

The MCP server

Connect Claude or ChatGPT through the MCP server

MCP is how AI assistants like Claude and ChatGPT connect to other apps. Add Operelio to yours once and sign in, then ask in your own words. Anything that changes your trails or your CRM waits for your yes.

Claude
ChatGPT

ClaudeExample

Which leads on the Inbound leads trail are held, and why?

Opereliolist_leads

17 are held. 12 scored 2 and 5 scored 1, so they stayed out of HubSpot.

Pause that trail while we fix the form.

Allow Operelio to run pause_trail?Inbound leads

DenyAllow

Paused. New leads wait in its folder until you switch it back on.

Add Operelio to your assistantIn Claude or ChatGPT, add a custom connector with this address, then sign in to Operelio. There's no key to paste.https://operelio.com/api/mcp
Ask what you want to knowFor example, which leads are held and why, or how last week's runs went.
Approve each changeTools that change your trails or CRM are marked, so your assistant asks you before running them.

Claude Code

claude mcp add --transport http operelio \  https://operelio.com/api/mcp

What it can do on your plan

Plan	Through the MCP server
Free	The 15 free tools, your own jobs and files, and your trails, their runs and leads. 5 jobs per person over 30 days, files up to 2 MB.
Starter	Adds live trails to pause and resume, Do Not Contact checks, CRM pushes and Bridgeant. Files up to 25 MB.
Pro and Agency	Everything above, and you can connect with an API key instead of a sign-in.

A job run from your assistant counts toward the same monthly jobs as the app. Reads don't count.

The tools your assistant gets

Claude will be able to work in your Operelio workspaces as you: see your workspaces and jobs, upload files, run Operelio's cleaning tools on them, download the results, see your trails, their runs and leads, pause and resume trails, check addresses against Do Not Contact, push results to your CRM, ask Bridgeant and run the work Bridgeant offers. Pausing, resuming and pushing to a CRM need a workspace admin.

Read

list_workspaces
get_job
get_download_link
list_trails
get_trail
list_trail_runs
get_run
list_leads
get_lead
check_dnc
list_crm_connections
get_push_status

Run and upload

upload_file
start_upload
finish_upload
run_tool
ask_bridgeant

Change, asks you first

pause_trail
resume_trail
push_job_to_crm
confirm_bridgeant_action

Your assistant sees only the workspaces you belong to, and loses access as soon as you're removed from one. Set up the MCP server

Webhooks

Get a webhook when a lead is held or pushed

A webhook is a short message Operelio sends to your own system the moment something happens, so your code doesn't have to keep asking. Add the address on the API keys page and pick its events.

A webhook endpoint in Operelio with its delivery log — An endpoint and its delivery log. Each delivery can be sent again.An endpoint on the API keys page, with its signing secret and a test button.

An endpoint and its delivery log. Each delivery can be sent again.An endpoint on the API keys page, with its signing secret and a test button.

Four events, and how they arrive

lead.heldA lead is held, with the reason as a code
lead.pushedA lead reached your CRM
run.completedA live trail run finished, parked, failed or was canceled
trail.pausedA trail stopped on its own

Signed: HMAC-SHA256 over the timestamp and the body, with the endpoint's own secret.
Retried: For about 2 days: after 1 minute, then 5, 15, and on up to 24 hours.
Logged: 30 days of deliveries, with a Resend button.
Endpoints: 3 on Pro, 10 on Agency.

What arrivesPOST

Operelio-Event: lead.heldOperelio-Delivery: 9b1c…Operelio-Timestamp: 1793629269Operelio-Signature: v1=5d2c…
{  "id": "9b1c…",  "type": "lead.held",  "createdAt": "2026-11-02T14:21:09Z",  "workspaceId": "a7d3…",  "data": {    "leadId": "c81e…",    "trailId": "4f2a…",    "folderId": "e05b…",    "reason": "low_score",    "at": "2026-11-02T14:21:08Z"  }}

Check the signature

const crypto = require("crypto");
function verify(secret, ts, body, sig) {  const want = "v1=" + crypto    .createHmac("sha256", secret)    .update(`${ts}.${body}`)    .digest("hex");  if (want.length !== sig.length) return false;  const age = Date.now() / 1000 - ts;  return Math.abs(age) < 300 &&    crypto.timingSafeEqual(      Buffer.from(want), Buffer.from(sig));}

import hmac, hashlib, time
def verify(secret, ts, body, sig):    msg = f"{ts}.".encode() + body    want = "v1=" + hmac.new(        secret.encode(), msg, hashlib.sha256).hexdigest()    age = time.time() - int(ts)    return (abs(age) < 300            and hmac.compare_digest(want, sig))

Check the body as it arrived, before you parse it. It carries ids, codes and times, never a lead's details, so fetch the lead through the API with its id. Read the webhooks guide

The docs

Read the docs

Start here

Your first call, your keys, and a full integration.

Guides

Trails and leads, Do Not Contact, your assistant and webhooks.

Reference

Every endpoint and tool, plus limits and errors.

Connecting a form, Zapier or your CRM instead? See every integration

Questions

API and MCP questions

Does Operelio have an API?

Yes. Operelio's REST API at operelio.com/api/v1 reads and runs your trails, leads, tools, Do Not Contact list and CRM pushes, with an API key. It's on Pro and Agency.

Does Operelio have an MCP server?

Yes. Operelio's MCP server at operelio.com/api/mcp lets Claude, ChatGPT and other MCP clients, once you sign in, read trails and leads, run tools, check Do Not Contact and push to your CRM. It works on every plan, within that plan's limits. Changes to your trails or CRM wait for your yes.

Which plans include the API?

Operelio's API is on Pro, with 1,000 calls a month, and Agency, with 5,000. Free and Starter can use the MCP server with a sign-in.

Do reads count toward the API limit?

No. Operelio counts writes, runs and Bridgeant questions that use a message toward your monthly calls. Reads are limited only to 60 requests a minute per key.

Can Operelio send webhooks?

Yes. Operelio posts lead.held, lead.pushed, run.completed and trail.paused to your https address, signed with HMAC-SHA256 and retried for about 2 days. Pro has 3 endpoints and Agency 10.

Can I push leads to my CRM through the API?

Yes. Operelio pushes a finished file to HubSpot, Salesforce or Pipedrive with POST /api/v1/jobs/{id}/push, through the CRM you connected in the app. A live trail pushes each lead on its own.

Connect Operelio to your code or your assistant

Start free and add Operelio to Claude or ChatGPT today. The API and webhooks come with Pro.

Get started free Read the quickstart