Vendo AI API & MCP

The Vendo AI Public API turns Vendo AI from a UI-only product into a fully programmable platform. Generate an API key, and you can drive the entire product — create AI agents, build audiences, launch multi-channel campaigns, manage your CRM pipeline, read analytics, and manage billing — all from your own code, Zapier/Make workflows, or directly through an AI assistant like Claude or ChatGPT via Model Context Protocol (MCP).

Quick Start

Get started in three steps:

1. Get your API key

Log in to app.vendo-ai.com, go to Settings → API & MCP, and click "Create my key". You'll need an active subscription or free trial. The key is shown once — copy it immediately.

2. Make your first request

curl -s https://api.vendo-ai.com/v1/billing/balance \
  -H "Authorization: Bearer vnd_live_YOUR_KEY_HERE" | jq .

# Response:
{
  "data": {
    "balance": 450
  }
}

3. Or connect via MCP

Add the Vendo AI MCP server to Claude Desktop, ChatGPT, or any MCP-compatible client:

{
  "mcpServers": {
    "vendo-ai": {
      "url": "https://api.vendo-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer vnd_live_YOUR_KEY_HERE"
      }
    }
  }
}

Authentication

API Key Format

Keys follow the pattern vnd_live_ + 64 hex characters (32 random bytes). Example:

vnd_live_8f3a27207c3dd1a49beed2a852275eb77892491daaa19541bb761300694a4d46
^^^^^^^^^
 prefix    ← 32 random bytes → hex

Passing Your Key

Include your key in every request using either header:

Authorization: Bearer vnd_live_YOUR_KEY
# or
X-API-Key: vnd_live_YOUR_KEY

Security Model

• Hashed storage — only the SHA-256 hash is stored. The raw key is shown once at creation.
• Workspace-bound — every key belongs to exactly one workspace. Cross-tenant access is structurally impossible.
• Scope-enforced — each route requires specific scopes (all granted by default). See Scopes Reference.
• No billing:write — a leaked key cannot move money. Top-ups and plan changes require the authenticated portal.
• Instant revocation — delete a key in Settings, and it's invalid on the next request.

Architecture

The Public API is a dedicated microservice (vendo-public-api, port 3015) that sits in front of all internal Vendo AI services. It enforces authentication, scopes, rate limiting, audit logging, and billing pre-checks in one place. The MCP adapter (vendo-mcp, port 3016) is a thin translation layer that converts MCP tool calls into /v1 REST requests.

Rate Limits

Default rate limit is 60 requests per minute per API key (sliding window). Response headers tell you your current state:

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Error Handling

All errors follow a consistent JSON structure:

{
  "code": "missing_scope",
  "message": "Required scope(s) not on key: agents:write"
}

Agents

The Agents API provides complete lifecycle management — from creating an AI sales agent to scanning a website, generating a conversational script, setting an avatar, and configuring connections (Google Meet, Telegram, Website Widget, Presentations).

Core Endpoints

Agent Credits & Analytics

Agent Pipeline Endpoints

These endpoints power the full onboarding flow — from scanning a website to generating a sales script:

curl -X PATCH https://api.vendo-ai.com/v1/agents/{id}/company \
  -H "Authorization: Bearer $VENDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Ltd",
    "company_website": "https://acme.com",
    "company_description": "…",
    "contact_channels": {
      "meeting_url": "https://calendly.com/acme/30min",
      "email": "sales@acme.com",
      "phone": "+44 20 1234 5678",
      "whatsapp": "+44 7700 900000",
      "telegram": "@acme_sales"
    }
  }'

Connection Endpoints

Preview Endpoints

Preview exactly what your agent would send before any campaign launch:

Campaigns

Campaigns are multi-channel outreach sequences. You can create a campaign, attach an audience, configure channels (email, LinkedIn, calls), and launch it — all through the API.

CRM

CRM — programmatic access to the built-in Vendo CRM. Leads are people who demonstrated interest: replied to your LinkedIn or email outreach, engaged one of your AI agents (widget, phone, Telegram), or booked a meeting — plus leads your team adds manually. Read your live pipeline, move cards between stages, reply to leads on their source channel, and enrich contacts from a LinkedIn URL. Scopes: crm:read, crm:write.

# Who replied to me this week?
curl -s https://api.vendo-ai.com/v1/crm/leads?range=7d&limit=20 \
  -H "Authorization: Bearer vnd_live_..."

# Reply to a lead on their source channel (LinkedIn or email)
curl -s -X POST https://api.vendo-ai.com/v1/crm/leads/LEAD_ID/reply \
  -H "Authorization: Bearer vnd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for getting back to me — does Tuesday 3pm work?"}'

# Enrich a person from LinkedIn before adding them
curl -s -X POST https://api.vendo-ai.com/v1/crm/leads/enrich \
  -H "Authorization: Bearer vnd_live_..." \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url": "https://www.linkedin.com/in/someone"}'

Audiences

curl -X POST https://api.vendo-ai.com/v1/audiences/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": ["VP Sales", "Head of Revenue"],
    "countries": ["United States"],
    "companySizes": ["small", "medium"],
    "industries": ["SaaS", "Technology"],
    "mustHaveEmail": true,
    "limit": 25
  }'

Audience Sets

Pre-built, ready-to-use audiences you can buy and launch outreach against without building filters yourself. Browsing is free; purchasing costs 2 credits per contact.

# 1. See what it would cost — nothing is charged
curl -X POST https://api.vendo-ai.com/v1/audiences/sets/{set_id}/buy \
  -H "Authorization: Bearer $VENDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# 2. Execute after reviewing the cost
curl -X POST https://api.vendo-ai.com/v1/audiences/sets/{set_id}/buy \
  -H "Authorization: Bearer $VENDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Vendo SDR

The SDR (Signal-Driven Revenue) module gives you full control over the autonomous discovery pipeline — 12 AI hunters that continuously scan the web for buying signals, discover prospects, and launch outreach.

Signal Search Lifecycle

Agent Signal Profile

Personas & Signals

SDR Outreach

SDR Observability

curl -H "Authorization: Bearer $VENDO_API_KEY" \
  "https://api.vendo-ai.com/v1/sdr/people/export.csv?search_id={search_id}" \
  -o contacts.csv

The 9 Signal Hunters

Billing

Full read-only billing access. A leaked API key cannot move money — all money-moving paths require the authenticated portal.

LinkedIn Accounts

LinkedIn sending capacity is the scarcest resource in outreach: LinkedIn enforces roughly 70–80 invitations per day per account, server-side, regardless of your configuration. If invite volume looks low, check how many healthy accounts are connected here first.

Destructive Action Protocol

Any action that's hard to undo requires a two-step confirmation. This protects against accidental launches and ensures AI assistants always show a preview before executing.

How It Works

Protected Routes

• DELETE /v1/agents/:id — deleting an agent
• DELETE /v1/campaigns/:id — deleting a campaign
• POST /v1/campaigns/:id/launch — launching outreach
• POST /v1/agents/:id/deep-scan — deep website scan (15 credits)
• DELETE /v1/sdr/searches/:id — deleting a Signal Search
• DELETE /v1/sdr/searches/:id/outreach — deleting SDR outreach
• POST /v1/sdr/searches/:id/outreach/launch — launching SDR outreach
• POST /v1/sdr/searches/:id/run-now — manually triggering a hunter (paid sources spend credits)
• DELETE /v1/crm/leads/:id — soft-deleting a CRM lead
• DELETE /v1/crm/pipeline-stages/:id — deleting a CRM pipeline stage
• POST /v1/audiences/sets/:id/buy — buying an Audience Set (spends credits)
• POST /v1/audiences/sets/:id/launch — buying + launching outreach on an Audience Set
• POST /v1/linkedin/accounts/:id/reconnect — re-authenticating a LinkedIn account (changes its id)
• DELETE /v1/linkedin/accounts/:id — disconnecting a LinkedIn account

# Step 1: Preview
curl -X POST https://api.vendo-ai.com/v1/campaigns/abc123/launch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# Response: preview of what would happen
{
  "data": {
    "dry_run": true,
    "would_do": "Launch campaign \"Q3 Outreach · Jun 15, 2026 12:25\"",
    "campaign_name": "Q3 Outreach · Jun 15, 2026 12:25",
    "recipient_count": null,
    "channels": ["email", "linkedin"],
    "daily_limit": 100,
    "note": "Confirm to actually start. Once launched, contacts begin receiving outreach."
  }
}

# Step 2: Execute after human review
curl -X POST https://api.vendo-ai.com/v1/campaigns/abc123/launch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Idempotency

For any POST / PATCH / DELETE request, pass an Idempotency-Key header. The API guarantees that replaying the same request with the same key returns the same result without re-executing the side effect.

curl -X POST https://api.vendo-ai.com/v1/campaigns \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Outreach", "agent_id": "..."}'

# Second call with same key → replays cached response.
# Look for the X-Idempotency-Replay: true response header — it tells you
# the request hit the cache instead of running the side effect.

• Same key + same request → cached replay (no side effects)
• Same key + different request → 409 idempotency_conflict
• TTL: 24 hours (keys expire after that)
• Namespace: per API key (no cross-tenant collisions)

MCP — Model Context Protocol

The Vendo AI MCP server exposes the entire /v1 API surface as 149 MCP tools that any compatible AI assistant (Claude, ChatGPT, Cursor, Windsurf, etc.) can call. Your AI assistant can create agents, search audiences, launch campaigns, and monitor results — all in natural language.

MCP Setup & Connection

Claude Desktop / Claude Code

{
  "mcpServers": {
    "vendo-ai": {
      "url": "https://api.vendo-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer vnd_live_YOUR_KEY_HERE"
      }
    }
  }
}

ChatGPT / Other MCP Clients

Point any MCP-compatible client at https://api.vendo-ai.com/mcp with your API key as the Bearer token. The server uses Streamable HTTP transport and returns a mcp-session-id header that the client must include in subsequent requests.

How MCP Authentication Works

• Your API key is presented as Authorization: Bearer vnd_live_… at session start
• vendo-mcp validates the key through vendo-public-api (same validation as REST)
• vendo-mcp holds no secrets itself — it's a pure pass-through
• Every MCP→API call carries X-Vendo-Via: mcp so you can distinguish AI activity in audit logs
• All security (scopes, rate limits, billing) is enforced in vendo-public-api

149 MCP Tools — Complete Reference

Tools are organized by domain. Destructive actions use paired tool names: preview_* shows what would happen, the action tool executes it. The model must explicitly pick the execute variant — this is stronger than a boolean flag.

MCP — Agent Tools (36)

Read Operations

Create & Configure

Preview (Non-Destructive)

Destructive Actions (Require Prior Preview)

MCP — Campaign & Audience Tools (23)

MCP — CRM & Communications Tools (33)

MCP — SDR Tools (38)

MCP — LinkedIn Tools (6)

MCP — Billing Tools (13)

MCP — Destructive Action Safety

In MCP, destructive actions use paired tool names instead of boolean flags. This is safer because the AI model must explicitly choose the execute variant — it can't accidentally pass confirm: true to a tool.

Guide: Create an Agent via API

The full agent onboarding pipeline:

# 1. Create the agent (description is REQUIRED — NOT NULL in DB).
AGENT=$(curl -s -X POST https://api.vendo-ai.com/v1/agents \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Agent", "description": "Outbound SDR for SaaS"}')
AGENT_ID=$(echo $AGENT | jq -r '.data.id')

# 2. (Optional) quick scan to fetch the company website's structure.
curl -s -X POST https://api.vendo-ai.com/v1/agents/scan \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"website_url": "https://example.com"}'

# 3. Set company info — REQUIRED before generate-script will work.
curl -s -X PATCH https://api.vendo-ai.com/v1/agents/$AGENT_ID/company \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Example Inc",
    "company_website": "https://example.com",
    "company_description": "We build internal tools for revenue teams."
  }'

# 4. Generate the conversational + email script (1 credit, 8-stage AI).
curl -s -X POST https://api.vendo-ai.com/v1/agents/$AGENT_ID/generate-script \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"script_style": "FRIENDLY_CASUAL", "purpose": "sales"}'

# 5. Set the avatar from a public URL. The API downloads and stores it locally.
curl -s -X PATCH https://api.vendo-ai.com/v1/agents/$AGENT_ID/avatar \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/avatar.jpg"}'

# 6. Preview what this agent would send before launching anything.
curl -s -X POST https://api.vendo-ai.com/v1/agents/$AGENT_ID/preview/email \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{}'

Guide: Launch a Campaign

# 1. Search for audience
curl -s -X POST https://api.vendo-ai.com/v1/audiences/search \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"positions": ["CTO", "VP Engineering"], "countries": ["United States"], "companySizes": ["small", "medium"]}'

# 2. Save the audience
AUDIENCE=$(curl -s -X POST https://api.vendo-ai.com/v1/audiences \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tech Leaders Q3", "search_params": {...}}')

# 3. Create campaign
CAMPAIGN=$(curl -s -X POST https://api.vendo-ai.com/v1/campaigns \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Outreach", "agent_id": "...", "audience_id": "..."}')
CAMPAIGN_ID=$(echo $CAMPAIGN | jq -r '.data.id')

# 4. Preview launch (dry_run)
curl -s -X POST https://api.vendo-ai.com/v1/campaigns/$CAMPAIGN_ID/launch \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# 5. Launch after review
curl -s -X POST https://api.vendo-ai.com/v1/campaigns/$CAMPAIGN_ID/launch \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Guide: SDR Signal Pipeline

# 0. (Optional) Preview the AI-generated profile before creating the search
curl -s -X POST https://api.vendo-ai.com/v1/sdr/searches/preview \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_UUID"}'

# 1. Create a signal search (target_regions is required by the wizard).
#    workspace_id and user_id are injected automatically from your API key.
SEARCH=$(curl -s -X POST https://api.vendo-ai.com/v1/sdr/searches \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VP Sales hunt — US",
    "agent_id": "AGENT_UUID",
    "target_regions": ["US"],
    "enabled_sources": ["linkedin_jobs", "connected_people"]
  }')
SEARCH_ID=$(echo $SEARCH | jq -r '.data.search.id')

# 2. List people the hunters discovered
curl -s "https://api.vendo-ai.com/v1/sdr/people?search_id=$SEARCH_ID&limit=20" \
  -H "Authorization: Bearer $KEY"

# 3. Check signal stats for that search (default window: last 30 days)
curl -s "https://api.vendo-ai.com/v1/sdr/searches/$SEARCH_ID/stats" \
  -H "Authorization: Bearer $KEY"

# 4. Export people to a saveable audience that any campaign can use
curl -s -X POST https://api.vendo-ai.com/v1/sdr/people/export-to-audience \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"search_id\": \"$SEARCH_ID\", \"name\": \"Signal-found leads\" }"

Guide: Zapier & Make Integration

Connect Vendo AI to 5,000+ apps through Zapier or Make (Integromat):

Zapier: Use Webhooks by Zapier

1. Add a "Webhooks by Zapier" action step
2. Choose "Custom Request"
3. Set method, URL (e.g., https://api.vendo-ai.com/v1/agents), and headers (Authorization: Bearer vnd_live_...)
4. Set Content-Type: application/json and add your request body

Make: Use HTTP module

1. Add an "HTTP: Make a request" module
2. Set URL, method, and headers identically
3. Parse the JSON response to use in subsequent steps

Scopes Reference

Every API key has a set of scopes that control which endpoints it can access. By default, all scopes are granted when you create a key.

Coverage & Limits

The API mirrors the web app: agents, campaigns, SDR discovery and outreach, audiences, the CRM and LinkedIn account management are all available programmatically.

Intentionally UI-only

Anything that moves money stays on the authenticated portal, so a leaked API key can never trigger a charge. These actions are deliberately NOT exposed by the Public API or MCP — Stripe Checkout / Customer Portal flows are inherently browser-bound:

• Subscription Checkout (POST /api/billing/stripe/create-checkout-session)
• One-time credit top-up Checkout (POST /api/billing/stripe/create-credit-checkout)
• Stripe Customer Portal redirect (POST /api/billing/stripe/customer-portal)
• Retry payment on an open invoice (POST /api/billing/stripe/pay-invoice)
• Cancel / resume a subscription (POST /api/billing/subscriptions/cancel|resume)
• Buy extra agent slot ($20/mo recurring add-on)
• Buy extra SDR sender pair ($20/mo recurring add-on)

Billing is fully readable — balance, subscription, pricing, transactions, invoices and credit-usage breakdowns — but never writable. There is no billing:write scope, and there will not be one. Customers who need automated top-ups can use the Stripe Customer Portal directly and set auto-recharge there. We are tracking webhook-based notifications (credits.low, subscription.canceled) as a future addition — see "What's Next" below.

Requires a Human Step

• Connecting a LinkedIn account. The API returns a hosted authorisation URL; a person must complete the flow in a browser.

Streaming

The web app uses server-sent events for live SDR activity. The API exposes the same data through polled endpoints (/v1/sdr/searches/:id/outreach/activity-feed) rather than a stream.

Changelog

2026-07-22 — Phase 7: Full UI Parity

• +30 REST endpoints (173 total) and +36 MCP tools (149 total) — everything you can do in the web app is now available programmatically, except payment operations
• New domains: Audience Sets marketplace and LinkedIn Accounts management
• CRM expanded: workspace members, calendar, notifications, settings, and the full outbound Communications stream
• SDR additions: CSV contact export, per-person provenance, activity feed, outreach summary
• Protected Routes grew from 8 to 12; scopes crm:read / crm:write registered for key issuance

2026-07-06 — CRM Domain Added

• 16 REST endpoints + 17 MCP tools for the built-in Vendo CRM
• Read your live pipeline, reply to leads on their source channel, manage kanban stages, and enrich contacts from LinkedIn
• New scopes: crm:read / crm:write
• Coverage grew to 6 domains with the CRM addition

2026-06-15 — Full Platform Coverage

• Phase 5c — 13 billing read-only tools and 13 endpoints (balance, subscriptions, invoices, usage)
• Phase 5b — 34 SDR tools, 37 endpoints covering the full signal pipeline
• Phase 5a — 29 agent tools, 59 endpoints covering full agent lifecycle
• Phase 4 — MCP server launched at api.vendo-ai.com/mcp
• Phase 2.5 — Destructive action protocol, idempotency keys
• Phase 3 — Frontend Settings → API & MCP tab shipped
• Phases 1–2 — Core API: agents read, campaigns CRUD, audiences, billing balance