Campaign endpoints

POST/campaigns

Create a draft campaign. Everything except name is optional and can be PATCHed later.

Success: 201 Created

POST /campaigns
{
  "name": "Q2 Outbound",
  "placeholderWord": "there",
  "pipLayout": "bottom-right",
  "pipDurationSeconds": 8
}

201 Created

{
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "userId": "...",
    "name": "Q2 Outbound",
    "status": "draft",
    "placeholderWord": "there",
    "greetingStartMs": 0,
    "greetingEndMs": 3000,
    "pipLayout": "bottom-right",
    "pipDurationSeconds": 8,
    "videoHost": "vimeo",
    "recordingMode": "desktop",
    "scrollStartSec": null,
    "scrollDownSec": null,
    "scrollPauseSec": null,
    "scrollUpSec": null,
    "disableScroll": true,
    "nameSpotlight": null,
    "liveRecordingOverlay": null,
    "createdAt": "2026-08-13T12:00:00.000Z",
    "updatedAt": "2026-08-13T12:00:00.000Z"
  }
}

GET/campaigns

List your campaigns, newest first. Soft-deleted campaigns are excluded.

Success: 200 OK

List rows carry recipientCount but not the per-status counts — fetch the campaign by id for those.

200 OK

{
  "data": [ { "id": "...", "name": "Q2 Outbound", "status": "completed", "recipientCount": 42, ... } ],
  "meta": { "page": 1, "perPage": 20, "total": 7, "totalPages": 1 }
}

GET/campaigns/:id

Fetch one campaign with its live recipient breakdown.

Success: 200 OK

This endpoint self-heals a stuck campaign: if the status is still rendering while every recipient has reached a terminal state, it transitions to completed (or failed, if nothing succeeded) before responding. That path does not deliver a campaign.completed webhook, so do not use polling as a substitute for one.

200 OK

{
  "data": {
    "id": "...",
    "name": "Q2 Outbound",
    "status": "completed",
    "recipientCount": 42,
    "completedCount": 40,
    "failedCount": 1,
    "degradedCount": 1,
    "cancelledCount": 0,
    "...": "all campaign-object fields"
  }
}

PATCH/campaigns/:id

Partial update. Only the keys you send are written; draft campaigns only.

Success: 200 OK

PATCH /campaigns/9a8b7c6d-...
{ "placeholderWord": "there", "pipDurationSeconds": 10 }

200 OK

{ "data": { /* the updated campaign object */ } }

DELETE/campaigns/:id

Soft-delete. The campaign disappears from lists and is purged for good after a 7-day grace period.

Success: 204 No Content

Any status except rendering can be deleted, not just drafts. Undo with POST /campaigns/:id/restore while the grace period lasts.

POST/campaigns/:id/ready

Lock the draft for launch. Verifies the campaign has a base video, that the video has finished processing, and that it has at least one recipient.

Success: 200 OK

200 OK

{ "data": { "id": "...", "status": "ready", ... } }

POST/campaigns/:id/unready

Send a ready campaign back to draft so its settings, asset and recipients become editable again.

Success: 200 OK

200 OK

{ "data": { "id": "...", "status": "draft", ... } }

POST/campaigns/:id/launch

Enqueue a render for every pending recipient and move the campaign to rendering. This is the call that spends quota.

Success: 200 OK

Launching is atomic against itself: a double-click or a retried request cannot enqueue every recipient twice. Renders are billed one at a time as they succeed, not charged up front, and a degraded render is never billed.

200 OK

{
  "data": { "id": "...", "status": "rendering", ... },
  "meta": { "jobsEnqueued": 42 }
}

POST/campaigns/:id/cancel

Stop a rendering campaign: aborts in-flight jobs, drops queued ones, and marks untouched recipients cancelled.

Success: 200 OK

Cancelled recipients were never charged — billing happens per successful render, so there is nothing to credit back.

200 OK

{
  "data": { "id": "...", "status": "cancelled", ... },
  "meta": { "cancelledRecipients": 12, "removedJobs": 9 }
}

POST/campaigns/:id/retry-failed

Re-queue every failed, degraded, cancelled and orphaned-queued recipient in one call, at retry priority.

Success: 200 OK

Nothing to retry is a success, not an error: the call returns 200 with meta.jobsEnqueued: 0. Each retried recipient re-rolls its TTS take, so a bad-sounding greeting is redrawn rather than reproduced.

200 OK

{
  "data": { "id": "...", "status": "rendering", ... },
  "meta": { "jobsEnqueued": 3 }
}

POST/campaigns/:id/retry-recipient/:recipientId

Re-queue exactly one recipient, at retry priority.

Success: 200 OK

The source-drift refusal exists because the cloned voice is a function of the base recording: retrying against a replaced video would ship a recipient a video in a different voice from the rest of the campaign.

200 OK

{
  "data": { "id": "...", "status": "rendering", ... },
  "meta": { "jobsEnqueued": 1, "jobId": "render-..." }
}

POST/campaigns/:id/restore

Undo a soft-delete within the 7-day grace period.

Success: 200 OK

Restoring a campaign that is not deleted is a no-op success, not an error.

200 OK

{ "data": { "id": "...", "deletedAt": null, ... } }

POST/campaigns/:id/clone

Copy a campaign's settings, base video and recipient list into a fresh draft. Recipients come back as pending; nothing is rendered.

Success: 201 Created

The base video is deep-copied into the new campaign, so deleting the source later does not break the clone. If any step fails the whole clone is rolled back — you never get a half-built campaign.

POST /campaigns/9a8b7c6d-.../clone
{ "name": "Q3 Outbound" }

201 Created

{ "data": { "id": "<new id>", "name": "Q3 Outbound", "status": "draft", "recipientCount": 42, ... } }