# ColdPegion REST API v1

> Everything ColdPegion can do — agents, leads, campaigns, inbox, deliverability, team — over plain HTTPS + JSON. The REST API, the MCP server, and the in-app AI Sidekick all execute the same operations, so anything an AI can do over MCP you can do here.

- **Base URL**: `https://coldpegion.com/api/v1`
- **Auth**: `Authorization: Bearer cp_live_…` — create a key in Dashboard → Connect to Claude / API. The same key authenticates MCP.
- **Scopes**: keys carry `read` and/or `write`; each endpoint lists which it needs.
- **Rate limit**: 120 requests/min per key. Watch `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; 429s include `Retry-After`.
- **Idempotency**: send an `Idempotency-Key` header on mutating requests to retry safely — replays return the original response with `Idempotency-Replayed: true`.
- **Responses**: success → `{ "data": …, "request_id": "req_…" }`; errors → `{ "error": { "type", "message", "param"? }, "request_id" }`.
- **Error types**: `authentication_error` (401), `permission_error` (403), `invalid_request_error` (400), `not_found_error` (404), `rate_limit_error` (429), `api_error` (500).
- **Entity references**: path params accept an id **or** the entity's exact name (case-insensitive) — `POST /agents/Fintech Outbound/launch` works.
- **GET parameters** go in the query string; all other methods take a JSON body.
- **Machine-readable spec**: `GET https://coldpegion.com/api/v1/openapi.json` (OpenAPI 3.1).
- **Introspection**: `GET /v1/me` returns the key's user, org, role, and scopes.

## Quick start

```bash
curl https://coldpegion.com/api/v1/overview -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

## Account

### `GET /overview`

Get a high-level overview of the account: counts of agents, prospects, lists, products and mailboxes, plus the daily email limit.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/overview \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `GET /company`

Get the user's company profile.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/company \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `PATCH /company`

Create or update the company profile fields.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `companyName` | string | no | — |
| `industry` | string | no | — |
| `description` | string | no | — |
| `valuePropositions` | string | no | — |
| `toneOfVoice` | string | no | — |

```bash
curl -X PATCH https://coldpegion.com/api/v1/company \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyName":"…","industry":"…"}'
```

### `PATCH /settings/daily-limit`

Set the global daily email limit (safety cap across all agents).

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | **yes** | — |

```bash
curl -X PATCH https://coldpegion.com/api/v1/settings/daily-limit \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":10}'
```

## Agents

### `POST /campaigns`

Create a draft campaign from a brief with its offer and audience automatically. Does not send. Choose reviewMode: COLDPEGION (default, user approves in app), MCP_CLIENT (ask user in this client before approval), or AUTO (no review). Reuse requestId on retries. Then import contacts, configure_agent with senderEmails, set_agent_sequence or prepare_emails, review as required, and launch_agent.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `requestId` | string | **yes** | — |
| `brief` | string | **yes** | — |
| `timezone` | string | no | — |
| `reviewMode` | "MCP_CLIENT" \| "COLDPEGION" \| "AUTO" | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/campaigns \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"…","brief":"…"}'
```

### `GET /agents/{agent}/contacts`

Page through this campaign's contacts to write individually personalized emails. Use only supplied facts. DNC contacts must not be contacted. Cursor is the last returned prospect id.

Scope: `read`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `cursor` | string | no | — |
| `limit` | integer | no | — |

```bash
curl https://coldpegion.com/api/v1/agents/{agent}/contacts \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `GET /agents/{agent}/review`

Read exact per-recipient messages, revisions, reviewEpoch and approval states. In MCP_CLIENT mode show these to the user and ask approval before approve_campaign_emails. In COLDPEGION mode send the user to reviewUrl. Pagination must be respected; never approve unseen pages.

Scope: `read`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `cursor` | string | no | — |
| `limit` | integer | no | — |

```bash
curl https://coldpegion.com/api/v1/agents/{agent}/review \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /agents/{agent}/review/prepare`

Materialize a small batch of exact per-person messages for review from a static/AI campaign. Built-in AI usage is charged for generated messages. For EXTERNAL campaigns write each person's message yourself with prepare_emails instead. Repeat while remaining > 0, then get_campaign_review.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


```bash
curl -X POST https://coldpegion.com/api/v1/agents/{agent}/review/prepare \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `GET /agents`

List AI agents with status and how many emails each has sent.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/agents \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /agents`

Create an AI outreach agent, wiring up products, a target list, sender mailbox(es) and guidelines. Does NOT launch it.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | **yes** | — |
| `description` | string | no | — |
| `listName` | string | **yes** | — |
| `productNames` | string[] | no | — |
| `senderEmails` | string[] | no | — |
| `sequenceMode` | "AI_GENERATED" \| "STATIC" \| "EXTERNAL" | no | — |
| `guidelines` | string | no | — |
| `reviewMode` | "MCP_CLIENT" \| "COLDPEGION" \| "AUTO" | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/agents \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","listName":"…"}'
```

### `PATCH /agents/{agent}`

Update an agent's sending cadence, daily limit, schedule, guidelines or sequence mode.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `guidelines` | string | no | — |
| `sequenceMode` | "AI_GENERATED" \| "STATIC" \| "EXTERNAL" | no | — |
| `dailyEmailLimit` | integer | no | — |
| `minIntervalMinutes` | integer | no | — |
| `maxIntervalMinutes` | integer | no | — |
| `randomDelayMax` | integer | no | — |
| `scheduleStartHour` | integer | no | — |
| `scheduleEndHour` | integer | no | — |
| `scheduleDays` | string | no | — |
| `scheduleTimezone` | string | no | — |
| `senderEmails` | string[] | no | — |

```bash
curl -X PATCH https://coldpegion.com/api/v1/agents/{agent} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"guidelines":"…","sequenceMode":"AI_GENERATED"}'
```

### `POST /agents/{agent}/launch`

Launch a campaign. MCP_CLIENT requires user-confirmed approval of exact email revisions first. COLDPEGION requires approval in the app. AUTO needs no review. Normal sender, suppression and schedule checks always apply.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


```bash
curl -X POST https://coldpegion.com/api/v1/agents/{agent}/launch \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /agents/{agent}/pause`

Pause an agent so it stops sending.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


```bash
curl -X POST https://coldpegion.com/api/v1/agents/{agent}/pause \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /agents/{agent}/clone`

Duplicate an existing agent's configuration as a new DRAFT.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


```bash
curl -X POST https://coldpegion.com/api/v1/agents/{agent}/clone \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `PUT /agents/{agent}/sequence`

Set an agent's static multi-step sequence (subject/body templates with {{firstName}}, {{companyName}}, {{jobTitle}} variables). Bodies accept plain text or safe HTML fragments (p, strong, em, ul/li, a). Unsafe HTML is removed at delivery. No platform LLM is used. Pause before changing content; earlier approvals are invalidated.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `steps` | object[] | **yes** | — |

```bash
curl -X PUT https://coldpegion.com/api/v1/agents/{agent}/sequence \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{}]}'
```

### `POST /agents/{agent}/prepared-emails`

Bulk-push pre-written, per-lead emails for an agent (one unique email per prospect). Bodies accept plain text or safe HTML fragments (p, strong, em, ul/li, a). The worker sanitizes HTML and sends with NO platform LLM call — AI marketing at scale, paid by your own Claude. Up to 500 items/call; paginate for more. Switches the agent to EXTERNAL mode by default.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `items` | object[] | **yes** | — |
| `setExternalMode` | boolean | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/agents/{agent}/prepared-emails \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{}]}'
```

### `POST /authoring/campaign-content`

Use AI to write campaign guidelines and/or a multi-step email sequence, then optionally save them onto an agent.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `what` | "guidelines" \| "sequence" \| "both" | no | — |
| `productNames` | string[] | no | — |
| `campaignGoal` | string | no | — |
| `applyToAgent` | string | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/authoring/campaign-content \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"what":"guidelines","productNames":["…"]}'
```

## Leads & prospects

### `POST /verification/email`

Verify an address using the user's selected verifier: ZeroBounce or BillionVerify with their saved key, otherwise built-in checks. May consume their provider credits. UNKNOWN means mailbox existence was not established; never describe it as valid. Results update an owned prospect if present. No email is sent.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | **yes** | — |

```bash
curl -X POST https://coldpegion.com/api/v1/verification/email \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'
```

### `GET /prospect-lists`

List prospect lists with their prospect counts.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/prospect-lists \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /prospect-lists`

Create a new (empty) prospect list.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | **yes** | — |

```bash
curl -X POST https://coldpegion.com/api/v1/prospect-lists \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'
```

### `POST /prospects`

Add a single prospect to a list (creates/updates the prospect).

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `listName` | string | **yes** | — |
| `email` | string | **yes** | Prospect email address |
| `firstName` | string | no | — |
| `lastName` | string | no | — |
| `companyName` | string | no | — |
| `jobTitle` | string | no | — |
| `industry` | string | no | — |
| `location` | string | no | — |
| `timezone` | string | no | — |
| `seniority` | string | no | — |
| `department` | string | no | — |
| `phone` | string | no | — |
| `website` | string | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/prospects \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listName":"…","email":"…"}'
```

### `POST /prospects/import`

Bulk-import leads into a list (creates the list if it doesn't exist). Use this to push leads you mined from other connectors. Up to 500 per call — paginate for more.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `listName` | string | **yes** | — |
| `leads` | object[] | **yes** | — |

```bash
curl -X POST https://coldpegion.com/api/v1/prospects/import \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listName":"…","leads":[{}]}'
```

### `POST /leads/search`

Search for leads (Instantly/Apollo-style) by filters, in the shared lead database, the user's prospects, or Apollo (if configured). Optionally import the results into a list.

Scope: `read`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `jobTitles` | string[] | no | — |
| `seniorities` | string[] | no | — |
| `industries` | string[] | no | — |
| `locations` | string[] | no | — |
| `headcount` | string[] | no | — |
| `keywords` | string[] | no | — |
| `source` | "global" \| "database" \| "apollo" | no | — |
| `importIntoListName` | string | no | — |
| `limit` | integer | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/leads/search \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobTitles":["…"],"seniorities":["…"]}'
```

### `PUT /prospects/do-not-contact`

Add or remove a prospect from the do-not-contact (DNC) list by email. DNC prospects are skipped by all campaigns.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | **yes** | Prospect email address |
| `block` | boolean | no | — |

```bash
curl -X PUT https://coldpegion.com/api/v1/prospects/do-not-contact \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'
```

### `POST /suppressions`

Add email addresses or whole domains (e.g. 'acme.com') to the global suppression list. Suppressed addresses are NEVER emailed by any campaign, even if imported as prospects later — use for compliance opt-outs, customers, competitors.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `values` | string[] | **yes** | Emails ('a@b.com') and/or domains ('b.com' or '@b.com') |

```bash
curl -X POST https://coldpegion.com/api/v1/suppressions \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values":["…"]}'
```

## Products

### `GET /products`

List the user's products with their ICP.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/products \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /products`

Create a new product the agents can market. Optionally include an ICP description.

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | **yes** | — |
| `description` | string | no | — |
| `usps` | string | no | — |
| `targetAudience` | string | no | — |
| `icpPrompt` | string | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/products \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'
```

### `PATCH /products/{product}`

Update an existing product by id or name.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `product` | string | **yes** | Entity id — or its exact name (case-insensitive). |


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | no | — |
| `description` | string | no | — |
| `usps` | string | no | — |
| `targetAudience` | string | no | — |
| `icpPrompt` | string | no | — |

```bash
curl -X PATCH https://coldpegion.com/api/v1/products/{product} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","description":"…"}'
```

### `DELETE /products/{product}`

Delete a product. Destructive — only call with confirm:true after the user explicitly confirms.

Scope: `write`

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `product` | string | **yes** | Entity id — or its exact name (case-insensitive). |


```bash
curl -X DELETE https://coldpegion.com/api/v1/products/{product} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

## Mailboxes & deliverability

### `GET /email-accounts`

List the mailboxes available to the user (owned, assigned, or shared by the org), with provider and daily usage.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/email-accounts \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `GET /deliverability`

Get per-domain and per-mailbox deliverability stats (sent, reply rate, bounce rate, today's utilization) to decide which mailbox/domain to send from. Pro plan module.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/deliverability \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

## Inbox

### `GET /inbox/replies`

Get the most recent inbound replies with their AI category (INTERESTED, NOT_INTERESTED, etc.).

Scope: `read`


**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | — |

```bash
curl https://coldpegion.com/api/v1/inbox/replies \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /inbox/sync`

Pull new inbound mail over IMAP for the user's mailboxes and detect replies now.

Scope: `write`


```bash
curl -X POST https://coldpegion.com/api/v1/inbox/sync \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

## Team

### `GET /team`

List organization members (with roles) and any pending join requests.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/team \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `POST /team/invites`

Invite a teammate to the organization by email (admins only).

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | **yes** | Email address to invite |
| `role` | "ADMIN" \| "MEMBER" | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/team/invites \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'
```

### `POST /team/join-requests`

Approve or deny a pending join request by the requester's email (admins only).

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | **yes** | Email address of the requester |
| `action` | "approve" \| "deny" | no | — |

```bash
curl -X POST https://coldpegion.com/api/v1/team/join-requests \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'
```

### `PATCH /team/members`

Change an organization member's role (admins only; only an owner can grant OWNER).

Scope: `write`


**Body parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | **yes** | Email address of the member |
| `role` | "OWNER" \| "ADMIN" \| "MEMBER" | **yes** | — |

```bash
curl -X PATCH https://coldpegion.com/api/v1/team/members \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…","role":"OWNER"}'
```

## Help

### `GET /help/topics`

List all ColdPegion help guides (slug, title, description, category). Use this to discover which guide answers a how-to or product question.

Scope: `read`


```bash
curl https://coldpegion.com/api/v1/help/topics \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

### `GET /help/guides`

Get the full content of a ColdPegion help guide. Pass an exact slug (from list_help_topics) or a free-text question (e.g. 'how do I connect gmail') and the best-matching guides are returned as markdown. ALWAYS use this to answer how-to, setup, billing, deliverability, or troubleshooting questions instead of guessing.

Scope: `read`


**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `slugOrQuery` | string | **yes** | A guide slug, or a free-text question to search for |

```bash
curl https://coldpegion.com/api/v1/help/guides \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"
```

---

Questions: support@coldpegion.com · Human-readable docs: https://coldpegion.com/docs/api