# Pipevoy

> Pipevoy is an AI SDR for LinkedIn. It watches for buying signals, finds the people who decide, drafts personal LinkedIn invites and follow-ups for approval, classifies replies, drafts answers with a booking link and tracks booked meetings. Sending runs through a safety engine: per-account warm-up, working hours, daily and weekly limits, randomised pacing and approvals.

Agents can run all of it without the web app, through the REST API or the MCP server.

## Key links
- [API docs](https://pipevoy.com/docs/api): authentication, every endpoint with curl examples, webhooks, MCP setup
- [OpenAPI 3.1](https://pipevoy.com/api/v1/openapi.json)
- [API index](https://pipevoy.com/api/v1): machine-readable endpoint list and getting-started sequence
- MCP server (Streamable HTTP): https://pipevoy.com/api/mcp with header Authorization: Bearer <API key>
- [MCP server card](https://pipevoy.com/api/mcp/server-card)
- [Pricing](https://pipevoy.com/pricing): API and MCP access is included in Growth and higher, and in the 14-day trial
- [Overview](https://pipevoy.com/): what the engine enforces and what a human still does

## Markdown versions of every page
Each is also served from the page URL itself for `Accept: text/markdown`, and in the browser with ?mode=agent.
- [Home](https://pipevoy.com/index.md)
- [API and MCP docs](https://pipevoy.com/docs/api.md)
- [Pricing](https://pipevoy.com/pricing.md)
- [How it works](https://pipevoy.com/how-it-works.md)
- [Headless overview](https://pipevoy.com/headless.md)

# Pipevoy: zero to booked meetings, no UI

Pipevoy is an AI SDR for LinkedIn. You (an agent) can sign up, configure, launch and manage outreach through the REST API (https://pipevoy.com/api/v1) or the MCP server (https://pipevoy.com/api/mcp). Pipevoy keeps the LinkedIn-safe sending engine: warm-up, daily and weekly limits, working hours, approvals and the billing gate are never bypassed.

Only three things need a person:
- Confirm the signup email (once).
- Log in to LinkedIn through each sender's connect_url (once per LinkedIn account).
- Pay through the Stripe Checkout link (before the trial ends).

## Sequence
1. **Sign up** (needs a person)
   - REST: `POST /api/v1/signup {"email":"you@company.com","company_name":"Acme"}`
   - MCP: `signup`
   - Returns id and claim_token. A verification link is emailed; a person opens it and confirms. That creates the workspace on a 14-day Growth trial (no card).
2. **Collect the API key**
   - REST: `GET /api/v1/signup/{id} with header X-Claim-Token: {claim_token}`
   - MCP: `signup_status`
   - Poll every 10-30 s. Once confirmed, the response contains api_key exactly once. Use it as Authorization: Bearer <key> from now on.
3. **Build the company profile**
   - REST: `POST /api/v1/company/analyze {"website":"https://acme.com"}, then PUT /api/v1/company to adjust ICP and personas`
   - MCP: `analyze_company, then update_company`
   - The AI reads the website and writes value props, ICP and personas. Every draft is written from this profile.
4. **Create a LinkedIn sender** (needs a person)
   - REST: `POST /api/v1/senders {"name":"Sara Khan","timezone":"America/New_York","booking_url":"https://cal.com/sara/intro"}`
   - MCP: `create_sender`
   - Returns connect_url. A person must open it once and log in to LinkedIn (hosted sign-in; the password is never seen). Poll GET /api/v1/senders/{id} until status is connected.
5. **Subscribe to events**
   - REST: `POST /api/v1/webhooks {"url":"https://agent.example.com/hooks","events":["draft.created","reply.received","meeting.booked"]}`
   - MCP: `create_webhook`
   - Optional: get draft.created, reply.received, meeting.booked and more pushed to you, signed with HMAC-SHA256. Or poll the list endpoints.
6. **Draft and launch a campaign**
   - REST: `POST /api/v1/campaigns/draft {"objective":"Book intro calls with RevOps leaders","cta":"a 20-minute call"}, then POST /api/v1/campaigns {name, steps, sender_ids, require_approval: true}`
   - MCP: `draft_campaign, then create_campaign`
   - require_approval defaults to true: every message waits for an approval, which your agent can give.
7. **Add and enroll prospects**
   - REST: `POST /api/v1/campaigns/{id}/enroll {"linkedin_urls":["https://www.linkedin.com/in/jane-doe"]}`
   - MCP: `enroll_prospects (or add_prospects first)`
   - Unknown URLs are added as prospects, deduplicated by LinkedIn URL. You can also push buying signals with POST /api/v1/signals.
8. **Approve drafts**
   - REST: `GET /api/v1/approvals, then POST /api/v1/approvals/{id}/approve (optionally {"body":"edited text"})`
   - MCP: `list_pending_approvals, approve_draft / reject_draft`
   - Approved messages go out inside the sender's working hours, limits and warm-up. Nothing bypasses the safety engine or the billing gate.
9. **Handle replies**
   - REST: `GET /api/v1/conversations?since=…, GET /api/v1/conversations/{id}, POST /api/v1/conversations/{id}/reply {"body":"…"}`
   - MCP: `list_conversations, get_conversation, draft_reply`
   - Replies are classified automatically and the AI drafts an answer with the booking link. A reply you write is a draft too; approve it to send.
10. **Track meetings**
   - REST: `GET /api/v1/meetings, PATCH /api/v1/meetings/{id} {"status":"held","qualified":true}`
   - MCP: `list_meetings, update_meeting`
   - Bookings through the sender's booking link appear here. Mark held, no-show or qualified; a no-show drafts a rebook note for approval.
11. **Pay before the trial ends** (needs a person)
   - REST: `GET /api/v1/billing, POST /api/v1/billing/checkout {"plan":"growth","interval":"month"}`
   - MCP: `get_billing, create_checkout_link`
   - Returns a Stripe Checkout URL. A person must open it and pay. When the trial ends unpaid, sending pauses; no data is deleted.

## Rules of the road
- Authenticate with `Authorization: Bearer pv_…`. 120 requests per minute per key; 429 responses carry Retry-After.
- Send an `Idempotency-Key` header on POSTs so retries never double-create.
- Errors are `{ "error": { "code", "message", "hint" } }`; the hint says what to do next.
- Lists are cursor-paginated: `?limit=` (max 100) and `&cursor=` from `next_cursor`.
- Nothing is sent to LinkedIn directly by an API call. Approving queues a message; the engine sends it when the sender's schedule and limits allow.

Docs: https://pipevoy.com/docs/api · OpenAPI: https://pipevoy.com/api/v1/openapi.json

## Key workflows
- Signal-led outreach: push signals (POST /api/v1/signals) from Clay, a CRM or your own research; signal campaigns enroll matching stakeholders within a daily cap.
- Agent as approver: keep require_approval on, subscribe to draft.created (POST /api/v1/webhooks) or poll GET /api/v1/approvals, then approve, edit or reject.
- Reply handling: subscribe to reply.received, read GET /api/v1/conversations/{id}, then approve the AI's reply draft or write your own with POST /api/v1/conversations/{id}/reply (a draft; it still needs approval).
- Agencies: one API key per client workspace.