Update, Delete & Branch

Manage existing campaigns: rename them, delete them (with a data-preserving cascade), and branch a new campaign from an existing one at a chosen step.

All endpoints require the campaigns:write scope and operate only on campaigns in the API key's workspace.

Rename a campaign

PATCH /api/v1/campaigns/:id · scope campaigns:write

Updates a campaign's display name.

Path parameters

Request body

Example request

curl -X PATCH "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q2 Enterprise Outreach" }'

Response (200 OK)

{
  "id": "uuid",
  "name": "Q2 Enterprise Outreach",
  "created_at": "2025-01-15T12:00:00.000Z"
}

Error responses

Delete a campaign

DELETE /api/v1/campaigns/:id · scope campaigns:write

Deletes a campaign and its regenerable artifacts (configuration, system prompts, asset selections, previews, generated documents, conversations, etc.).

Your lead data is preserved. Lists that belonged to this campaign are detached and retained — their rows and uploaded/processed CSV files in storage are not deleted. After deletion, those lists have campaign_id: null and remain accessible via the Lists endpoints (and exportable). Credit usage history is also retained for auditing.

In-flight guard: If any list in the campaign is currently processing, the request returns 409 CONFLICT. Wait until those lists complete or fail, then retry.

Path parameters

Example request

curl -X DELETE "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{ "id": "uuid", "deleted": true }

Error responses

Branch a campaign

POST /api/v1/campaigns/:id/branch · scope campaigns:write

Creates a new campaign that reuses the source campaign's configuration up to a chosen step. Everything from the branch step onward is left for you to (re)configure on the new campaign. This is synchronous and does not consume credits.

Path parameters

Headers

Request body

target_audience object:

Example request

curl -X POST "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID/branch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme – Mid-Market Variant",
    "branch_from_step": "social-proof"
  }'

Response (201 Created)

{
  "id": "new-campaign-uuid",
  "source_campaign_id": "uuid"
}

Error responses