Build on Venom Funnel and Outreach
Work with deals, pipelines, products, goals, reports and Outreach sequences from code or an agent, over REST or MCP, as the member whose People the deals link.
Venom Funnel is the deal pipeline built on Venom People: the people on a deal are People, and what you log on a deal
lands on your own people as interactions. Outreach, the follow-up sequences, lives inside Funnel. Everything an agent
needs from the board, the deal page, Settings and Reports is an MCP tool on /workspace/mcp/funnel and a REST route
under /api/v1/funnel. Outreach also has its own REST API under /v1/outreach.
What you can build
- Deals from your sign-up or billing system. Open a deal for a new account with
POST /api/v1/funnel/deals(orfunnel_deal_create), linking the people you already have in People, and move it withPOST /api/v1/funnel/deals/{deal}/movewhen the account converts. - A call logger. After a call, log it on the deal and add a to-do with one
PATCH /api/v1/funnel/deals/{deal}(logandtodo). The to-do is a Venom Tasks issue linked to the deal. - Forecast and goal reports. Read the weighted forecast, win rate, velocity or lost reasons with
GET /api/v1/funnel/reportsand goal attainment withGET /api/v1/funnel/goalsinto your own dashboard. - Quotes from your catalogue. Keep products in sync with
funnel_product_saveand add product lines to a deal withPOST /api/v1/funnel/deals/{deal}/items; the deal's value becomes their sum. - Event follow-ups. After a conference, list the people met there with
funnel_outreach_event_previewand enroll them in a sequence withfunnel_outreach_person_enroll(consent_basis: met_in_person,dry_runfirst). - A deal assistant. Connect
venom-funneland let an agent find stale deals withfunnel_deal_list, read one withfunnel_deal_getand prepare the next step for the member to review.
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/funnel, server name venom-funnel |
| Connect | claude mcp add --transport http venom-funnel https://cloud.usevenom.dev/workspace/mcp/funnel |
| MCP tools | 38 (14 read, 24 write) |
| OAuth scopes | funnel:read funnel:write; people:read and people:write also open these tools |
| REST twin | 42 routes under https://cloud.usevenom.dev/api/v1 |
| Outreach API | 13 operations |
| Webhook events | funnel.deal.created, funnel.deal.updated, funnel.deal.stage_changed, funnel.deal.archived |
Authentication and scopes
A deal links the member's own People, so Funnel always acts as one member, the same caller as People:
- A personal API key (
vck_…with a member) acts as that member. Every org role can read and change deals today (Funnel's row in the role matrix is held at write for billing and viewer too). A key marked read-only reads only. - A team key has no member and is refused on every Funnel tool and
/api/v1/funnelroute, with a message that says so. The Outreach API under/v1/outreachis the exception: there a team key acts for the org (below). - An OAuth app needs
funnel:readto use the tools andfunnel:writeto change anything. Grants made withpeople:readandpeople:writebefore Funnel had its own scopes still open Funnel's tools. - A service agent that an admin scoped to some apps reaches Funnel only when People is one of them, because Funnel runs as the People caller.
The caller sees what the member sees: deals with visibility: team only when they are in that team, and on each deal
only the people they may see. A hidden contact shows as a count.
There is no Funnel add-on: every member of an organisation has it. A todo creates a Tasks issue, so it needs the
Tasks add-on. A refused change answers 403 over REST, or a tool error that names funnel:write over MCP.
Outreach adds one rule: an API key or an agent counts as an agent for approval. funnel_outreach_run_approve and
POST /v1/outreach/runs/{id}/approve are refused unless the sequence sends without approval; a person approves the
draft in Funnel.
Worked example
Open a deal for a person you found with people_person_search, log the first call with a follow-up to-do, then move
the deal on:
curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"title": "Example Co · GPU cluster", "value": 250000, "currency": "USD", "stage": "Qualified",
"company": "Example Co", "expected_close": "2026-12-15",
"people": [{"person": "0b7c6f0e-5a3e-4c0f-9a52-3a8f1d2c4b11", "role": "champion"}]}'
curl -X PATCH "$VENOM_CLOUD/api/v1/funnel/deals/<deal-id>" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"log": {"kind": "call", "summary": "Intro call. They want a quote for 8 nodes."},
"todo": {"title": "Send the 8-node quote", "due": "2026-11-16"}}'
curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals/<deal-id>/move" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"stage": "Proposal"}'The same move over MCP, from any client connected to /workspace/mcp/funnel:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "funnel_deal_move",
"arguments": { "deal": "<deal-id>", "stage": "Proposal", "format": "json" } } }stage is a stage's name or id. Moving into a won or lost stage closes the deal; pass lost_reason for a lost one.
Every move is kept in the deal's stage history.
Values, formats and behaviour
- Money. Values in arguments are in major units (
12500.50):value, a product'sprice, a line'spriceand awon_valuegoal'starget. JSON answers carryvalueMinorin minor units (cents). - Answers. Tools answer short markdown; pass
format: "json"forstructuredContent. The REST twin always answers JSON. - Deal ids.
dealis the deal's id (a UUID). Pipelines, stages, products and fields also take a name (or a SKU for a product). - Deal value and product lines. While a deal has product lines, its
valueis their sum and avalueyou send is ignored. - Setup tools. Pipelines, stages, products, custom fields and goals change with the same checks as Settings: a new
pipeline needs a won and a lost stage; a stage's
kindchanges only while it holds no deals; archiving a stage moves its deals tomove_to; the default pipeline, or one with open deals, cannot be archived. A goaltargetof 0 or null removes the goal. - Reports.
reportissummary(default),conversion,win_rate,velocity,forecast,teamorlost_reasons;rangeis30d,90d,12morytd. - Retries. No Funnel tool takes an idempotency key, so a retried
POST /api/v1/funnel/dealscan open a second deal. Look the deal up withfunnel_deal_list(query) before you retry a create.
Outreach
Outreach tools are part of Funnel (funnel_outreach_*, same endpoint and scopes). They list and read your sequences
and those shared with your teams, save yours, enroll People with a consent basis, pause, resume or stop an
enrollment, list a sequence's enrollments (funnel_outreach_enrollment_list), list the queue of drafts to approve or
steps to send yourself, approve or skip a step, mark a tap-to-send step sent (funnel_outreach_run_mark_sent), and
preview one step's draft for one person. funnel_outreach_person_enroll with dry_run enrolls nobody and lists who would be
skipped and why (not_found, already_enrolled, opted_out, no_consent, no_address). Catch-ups use
funnel_outreach_catchup_get and funnel_outreach_catchup_set (default, reminder or a catch-up sequence id).
Two arguments exist only on the MCP tools, not on their /api/v1 twins: team on funnel_outreach_sequence_save
(share a sequence with a team) and sender on funnel_outreach_person_enroll (send your enrollments from your own
Comms senders). Use MCP, or the Outreach API below, when you need them.
The Outreach API
/v1/outreach is Outreach's own REST API, with an org API key like the rest of /v1. A member's personal key acts as
that member. A team key acts for the org: it lists every sequence, and a sequence it creates is owned by the key.
The OpenAPI document is services/nodejs-cloud/contracts/outreach-openapi.yaml; the docs build lists its operations in
the REST section of this page.
| Route | What |
|---|---|
GET, POST /v1/outreach/sequences |
list sequences, create one (teamId shares it with a team) |
GET, PUT, DELETE /v1/outreach/sequences/{id} |
read, replace or archive one (archiving stops every live enrollment) |
GET /v1/outreach/enrollments?sequence_id=, POST /v1/outreach/enrollments |
list a sequence's enrollments; enroll people (sequenceId, personIds, dealId, consentBasis, sender) |
POST /v1/outreach/enrollments/{id} |
pause, resume or stop one enrollment (action) |
GET /v1/outreach/queue?kind=approval or kind=manual |
drafts to approve, or steps to send yourself |
POST /v1/outreach/runs/{id}/approve, /skip, /tapped |
approve a draft (optionally with an edited subject or body), skip a step, mark a tap-to-send step sent |
Its fields are camelCase, as in contracts/outreach-v1.schema.json (TypeScript types in contracts/outreach.ts,
examples in contracts/fixtures/outreach). Every route is in the cloud API reference.
Rules for agents
- Search People first (
people_person_search), then link the person withfunnel_deal_createorfunnel_deal_update. - Move a deal when the situation changes and log what happened with
log: the forecast and the people's context cards depend on both. - A hidden contact shows as a count. Do not try to find out who it is.
- Never contact anyone on the user's behalf. Draft, and let the user approve or send.
Events
4 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| Event | When |
|---|---|
funnel.deal.created |
A deal visible to the whole org was created in Venom Funnel: id, title, value, currency, pipeline, stage, status, owner and company. Never its notes or the people on it; a team-only deal is never sent. |
funnel.deal.updated |
An org-wide deal's own fields changed (title, value, owner, company, expected close), or a team deal was opened to the org: the deal as it is now. A deal moved from the org to a team sends its id and visibility only. |
funnel.deal.stage_changed |
An org-wide deal moved to another stage: the stage before and after, its status (open, won or lost) as it is now, and who moved it. |
funnel.deal.archived |
An org-wide deal was archived: its id and title. |
Funnel and Outreach send no org webhook events. To follow changes, read deals with funnel_deal_list (sort and
filter by stage, status or owner) or a deal's history with funnel_deal_get.
REST routes
The REST twin: 42 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
/funnel/pipelines
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/pipelines |
List pipelines with their stages | funnel_pipeline_list |
| POST | /api/v1/funnel/pipelines |
Make a pipeline with its stages | funnel_pipeline_create |
| GET | /api/v1/funnel/pipelines/{pipeline} |
Read a pipeline with the count and value of its deals per stage | funnel_pipeline_get |
| PATCH | /api/v1/funnel/pipelines/{pipeline} |
Rename a pipeline or make it the default | funnel_pipeline_update |
| DELETE | /api/v1/funnel/pipelines/{pipeline} |
Archive a pipeline (no open deals, not the default) | funnel_pipeline_archive |
| POST | /api/v1/funnel/pipelines/{pipeline}/stages |
Add a stage to a pipeline | funnel_stage_create |
| PUT | /api/v1/funnel/pipelines/{pipeline}/stages |
Put a pipeline's stages in this order | funnel_stage_update |
/funnel/reports
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/reports |
Conversion, win rate, velocity, the weighted forecast and the team | funnel_report_get |
/funnel/goals
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/goals |
Sales goals with attainment and pace | funnel_goal_list |
| PUT | /api/v1/funnel/goals |
Set a sales goal (target 0 or null removes it), or change one by its goal id | funnel_goal_set |
/funnel/deals
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/deals |
List deals you may see | funnel_deal_list |
| POST | /api/v1/funnel/deals |
Open a deal | funnel_deal_create |
| GET | /api/v1/funnel/deals/{deal} |
Read a deal with its people, lines, history, activity and to-dos | funnel_deal_get |
| PATCH | /api/v1/funnel/deals/{deal} |
Change a deal, log an activity, add a to-do | funnel_deal_update |
| POST | /api/v1/funnel/deals/{deal}/move |
Move a deal to a stage | funnel_deal_move |
| POST | /api/v1/funnel/deals/{deal}/items |
Add a product line to a deal | funnel_item_create |
| PATCH | /api/v1/funnel/deals/{deal}/items/{item} |
Change a line of a deal | funnel_item_update |
| DELETE | /api/v1/funnel/deals/{deal}/items/{item} |
Remove a line from a deal | funnel_item_delete |
/funnel/stages
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PATCH | /api/v1/funnel/stages/{stage} |
Rename a stage or change its probability, type or stale-after days | funnel_stage_update |
| DELETE | /api/v1/funnel/stages/{stage} |
Archive a stage, moving its deals to move_to | funnel_stage_archive |
/funnel/products
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/products |
The product catalogue | funnel_product_list |
| POST | /api/v1/funnel/products |
Add a product | funnel_product_save |
| PATCH | /api/v1/funnel/products/{product} |
Change, archive or restore a product | funnel_product_save |
/funnel/outreach
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/outreach/sequences |
Your outreach sequences with their steps and counts | funnel_outreach_sequence_list |
| POST | /api/v1/funnel/outreach/sequences |
Create an outreach sequence | funnel_outreach_sequence_save |
| GET | /api/v1/funnel/outreach/sequences/{sequence} |
Read an outreach sequence | funnel_outreach_sequence_get |
| PUT | /api/v1/funnel/outreach/sequences/{sequence} |
Replace one of your outreach sequences | funnel_outreach_sequence_save |
| POST | /api/v1/funnel/outreach/enrollments |
Enroll People in an outreach sequence | funnel_outreach_person_enroll |
| POST | /api/v1/funnel/outreach/enrollments/{enrollment} |
Pause, resume or stop an enrollment | funnel_outreach_enrollment_set |
| GET | /api/v1/funnel/outreach/queue |
Drafts to approve or steps to send by hand | funnel_outreach_queue_list |
| POST | /api/v1/funnel/outreach/runs/{run}/approve |
Approve an outreach draft | funnel_outreach_run_approve |
| GET | /api/v1/funnel/outreach/sequences/{sequence}/enrollments |
A sequence's enrollments: who is in it, at which step, and why one stopped | funnel_outreach_enrollment_list |
| POST | /api/v1/funnel/outreach/runs/{run}/mark-sent |
Record that you sent a tap-to-send step yourself (Venom sends nothing); the enrollment moves on | funnel_outreach_run_mark_sent |
| POST | /api/v1/funnel/outreach/runs/{run}/skip |
Skip an outreach step | funnel_outreach_run_skip |
| POST | /api/v1/funnel/outreach/runs/{run}/hold |
Hold a timed draft so it never sends by itself | funnel_outreach_run_hold |
| POST | /api/v1/funnel/outreach/sequences/{sequence}/preview |
Preview a step's draft for one person | funnel_outreach_draft_preview |
| GET | /api/v1/funnel/outreach/catchups/{person} |
What a person's keep-warm cadence runs when it comes due | funnel_outreach_catchup_get |
| PUT | /api/v1/funnel/outreach/catchups/{person} |
Set a person's catch-up: default, reminder or a catch-up sequence | funnel_outreach_catchup_set |
| GET | /api/v1/funnel/outreach/events/{event} |
The people met at an event, ready to enroll | funnel_outreach_event_preview |
/funnel/fields
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/funnel/fields |
The org's custom deal fields | funnel_field_list |
| POST | /api/v1/funnel/fields |
Add a custom deal field | funnel_field_save |
| PATCH | /api/v1/funnel/fields/{field} |
Change, archive or restore a custom field | funnel_field_save |
Also the Outreach API: 13 operations, generated from services/nodejs-cloud/contracts/outreach-openapi.yaml. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime.
| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | /v1/outreach/sequences |
List sequences (yours and those shared with your teams; a team key sees every one) | key or token |
| POST | /v1/outreach/sequences |
Create a sequence (status draft unless given; approval every unless given) | key or token |
| GET | /v1/outreach/sequences/{id} |
Read a sequence | key or token |
| PUT | /v1/outreach/sequences/{id} |
Replace one of your sequences (steps replace its steps in order) | key or token |
| DELETE | /v1/outreach/sequences/{id} |
Archive one of your sequences; everyone still in it stops | key or token |
| GET | /v1/outreach/enrollments |
A sequence's enrollments, newest first (in a sequence shared with your team, only your own) | key or token |
| POST | /v1/outreach/enrollments |
Enroll People in a sequence, with the consent basis for contacting them | key or token |
| POST | /v1/outreach/enrollments/{id} |
Pause, resume or stop one of your enrollments | key or token |
| GET | /v1/outreach/queue |
What waits on you, oldest first (drafts to approve, or steps to send yourself) | key or token |
| POST | /v1/outreach/runs/{id}/approve |
Approve a draft, optionally edited; it goes out inside the send window | key or token |
| POST | /v1/outreach/runs/{id}/skip |
Skip a step; the enrollment moves on to the next | key or token |
| POST | /v1/outreach/runs/{id}/hold |
Hold a draft so it never sends by itself (a timed sequence's timer is removed); it waits for a person | key or token |
| POST | /v1/outreach/runs/{id}/tapped |
Record that you sent a tap-to-send step (or did a task) yourself | key or token |
MCP tools
38 tools: 14 read, 24 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
funnel_deal_create |
Create a deal | write | funnel:write |
POST /api/v1/funnel/deals |
funnel_deal_get |
Read a deal | read | funnel:read |
GET /api/v1/funnel/deals/{deal} |
funnel_deal_list |
List deals | read | funnel:read |
GET /api/v1/funnel/deals |
funnel_deal_move |
Move a deal to a stage | write | funnel:write |
POST /api/v1/funnel/deals/{deal}/move |
funnel_deal_update |
Change a deal | write | funnel:write |
PATCH /api/v1/funnel/deals/{deal} |
funnel_field_list |
List custom fields | read | funnel:read |
GET /api/v1/funnel/fields |
funnel_field_save |
Add or change a custom field | write | funnel:write |
POST /api/v1/funnel/fields (+1) |
funnel_goal_list |
List sales goals | read | funnel:read |
GET /api/v1/funnel/goals |
funnel_goal_set |
Set or remove a sales goal | write | funnel:write |
PUT /api/v1/funnel/goals |
funnel_item_create |
Add a line to a deal | write | funnel:write |
POST /api/v1/funnel/deals/{deal}/items |
funnel_item_delete |
Remove a line from a deal | write (destructive) | funnel:write |
DELETE /api/v1/funnel/deals/{deal}/items/{item} |
funnel_item_update |
Change a line of a deal | write | funnel:write |
PATCH /api/v1/funnel/deals/{deal}/items/{item} |
funnel_outreach_catchup_get |
Read a person's catch-up setting | read | funnel:read |
GET /api/v1/funnel/outreach/catchups/{person} |
funnel_outreach_catchup_set |
Set a person's catch-up sequence | write | funnel:write |
PUT /api/v1/funnel/outreach/catchups/{person} |
funnel_outreach_draft_preview |
Preview an outreach draft | write | funnel:write |
POST /api/v1/funnel/outreach/sequences/{sequence}/preview |
funnel_outreach_enrollment_list |
List a sequence's enrollments | read | funnel:read |
GET /api/v1/funnel/outreach/sequences/{sequence}/enrollments |
funnel_outreach_enrollment_set |
Pause, resume or stop an enrollment | write | funnel:write |
POST /api/v1/funnel/outreach/enrollments/{enrollment} |
funnel_outreach_event_preview |
Preview an event follow-up | read | funnel:read |
GET /api/v1/funnel/outreach/events/{event} |
funnel_outreach_person_enroll |
Enroll people in a sequence | write | funnel:write |
POST /api/v1/funnel/outreach/enrollments |
funnel_outreach_queue_list |
List the outreach queue | read | funnel:read |
GET /api/v1/funnel/outreach/queue |
funnel_outreach_run_approve |
Approve an outreach draft | write | funnel:write |
POST /api/v1/funnel/outreach/runs/{run}/approve |
funnel_outreach_run_hold |
Hold an outreach draft | write | funnel:write |
POST /api/v1/funnel/outreach/runs/{run}/hold |
funnel_outreach_run_mark_sent |
Mark a tap-to-send step sent | write | funnel:write |
POST /api/v1/funnel/outreach/runs/{run}/mark-sent |
funnel_outreach_run_skip |
Skip an outreach step | write | funnel:write |
POST /api/v1/funnel/outreach/runs/{run}/skip |
funnel_outreach_sequence_get |
Read an outreach sequence | read | funnel:read |
GET /api/v1/funnel/outreach/sequences/{sequence} |
funnel_outreach_sequence_list |
List outreach sequences | read | funnel:read |
GET /api/v1/funnel/outreach/sequences |
funnel_outreach_sequence_save |
Create or change an outreach sequence | write | funnel:write |
POST /api/v1/funnel/outreach/sequences (+1) |
funnel_pipeline_archive |
Archive a pipeline | write (destructive) | funnel:write |
DELETE /api/v1/funnel/pipelines/{pipeline} |
funnel_pipeline_create |
Create a pipeline | write | funnel:write |
POST /api/v1/funnel/pipelines |
funnel_pipeline_get |
Read a pipeline | read | funnel:read |
GET /api/v1/funnel/pipelines/{pipeline} |
funnel_pipeline_list |
List pipelines | read | funnel:read |
GET /api/v1/funnel/pipelines |
funnel_pipeline_update |
Rename a pipeline | write | funnel:write |
PATCH /api/v1/funnel/pipelines/{pipeline} |
funnel_product_list |
List products | read | funnel:read |
GET /api/v1/funnel/products |
funnel_product_save |
Add or change a product | write | funnel:write |
POST /api/v1/funnel/products (+1) |
funnel_report_get |
Read a funnel report | read | funnel:read |
GET /api/v1/funnel/reports |
funnel_stage_archive |
Archive a stage | write (destructive) | funnel:write |
DELETE /api/v1/funnel/stages/{stage} |
funnel_stage_create |
Add a stage | write | funnel:write |
POST /api/v1/funnel/pipelines/{pipeline}/stages |
funnel_stage_update |
Change or reorder stages | write | funnel:write |
PUT /api/v1/funnel/pipelines/{pipeline}/stages (+1) |
Related
- Venom Funnel: the board, deals, products, goals and reports.
- Funnel guides and Outreach: sequences, channels, safety rules and how drafts are written.
- Venom People: the people and companies deals link.
- Authentication and scopes, Errors, limits and pagination, MCP and REST.