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, 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:

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.

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
  }'

Vendo SDR

The SDR (Signal-Driven Revenue) module gives you full control over the autonomous discovery pipeline — 9 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

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.

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)

# 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 96 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

96 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 (35)

Read Operations

Create & Configure

Preview (Non-Destructive)

Destructive Actions (Require Prior Preview)

MCP — Campaign & Audience Tools (14)

MCP — SDR Tools (34)

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.

What's Intentionally Out of Scope (and Why)

These actions are deliberately NOT exposed by the Public API or MCP. They remain UI-only because a leaked API key must never move money outside the metering it already triggers, and 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)

There is no billing:write scope — one was never created. 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.

Changelog

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