ColdPilot API,
for your own machines.

Base URL

Production: https://usecoldpilot.com. Local development: http://localhost:3000. Every path below is relative to it.

Authentication

Create a key in Settings → API Keys (paid plans). Send it on every request as the x-api-key header — not as a query parameter, never in the URL. Keys come in two scopes:

• read — look only: list campaigns and leads.
• write — change things: create campaigns, edit sequences, import and delete leads.

A missing or wrong key answers 401; a valid key without the needed scope answers 403. Copy a new key once — it is shown a single time, stored hashed, and can be deleted any moment from the same screen.

curl https://usecoldpilot.com/api/campaigns \
  -H "x-api-key: cp_your_key_here"

Campaigns

GET /api/campaigns lists your campaigns (?id= fetches one). POST /api/campaigns creates a campaign as a draft — it needs a name and at least one step. Steps accept type (email), subject, body (first name and company spin with {{firstName}} tokens), and delayDays between touches:

curl -X POST https://usecoldpilot.com/api/campaigns \
  -H "x-api-key: cp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 outbound",
    "steps": [
      { "type": "email", "subject": "Quick question", "body": "Hi {{firstName}} — …", "delayDays": 0 },
      { "type": "email", "subject": "Re: Quick question", "body": "Bumping this up — …", "delayDays": 4 }
    ]
  }'

PATCH /api/campaigns?id=… edits a campaign, including replacing its steps array — this is how sequences are set and updated. DELETE /api/campaigns?id=… archives it (leads are kept or detached, never hard-deleted by this call).

Leads

GET /api/leads?campaignId=… lists leads, optionally filtered to one campaign. DELETE /api/leads?id=… removes one. Bulk upload goes through the import endpoint, which takes an array of lead objects — email plus optional firstName, lastName, company, title, and custom fields — and an optional campaignId to attach them to:

curl -X POST https://usecoldpilot.com/api/leads/import \
  -H "x-api-key: cp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "cm_abc123",
    "leads": [
      { "email": "[email protected]", "firstName": "Ada", "company": "Acme" },
      { "email": "[email protected]", "firstName": "Bob", "company": "Globex" }
    ]
  }'
// → { "imported": 2, "errors": 0, "skipped": 0, "total": 2, "firstError": null, "duplicates": 0 }

What keys cannot do

Keys cover campaigns, leads, and sequences only. Test sends, verification, inbox management, billing, and settings stay dashboard-only — deliberately, so no integration can spend money or fire real email by accident. Trial and account-standing rules apply to keys exactly as they do in the dashboard.