Campaigns API

Create and manage batch campaigns with schedules, frequency caps, and file output configuration. Trigger and monitor individual campaign runs.

See also: Runs concept and configuration for what this API powers, when to call it, and how it is configured.

Campaigns define recurring batch execution configurations. Each campaign targets a decision flow and customer segment, with schedule, volume, and file settings. Campaign runs are individual execution instances.

See the Campaigns feature page for UI guidance on creating and managing campaigns.

Base path

/api/v1/runs

---

List campaigns

GET /api/v1/runs

Returns a paginated list of campaigns with latest run info.

Query parameters

Parameter	Required	Type	Description
limit	No	integer	Max results per page. Default 50, max 200.
offset	No	integer	Records to skip. Default 0.

Response 200

{
  "runs": [
    {
      "id": "camp_001",
      "name": "Weekly High-Value Campaign",
      "status": "active",
      "scheduleType": "weekly",
      "scheduleDayOfWeek": 1,
      "scheduleTime": "09:00",
      "scheduleTimezone": "America/New_York",
      "decisionFlowName": "Q1 Cross-Sell",
      "segmentName": "High Value Customers",
      "segmentCustomerCount": 4521,
      "runCount": 3,
      "lastRunAt": "2026-03-15T14:00:00.000Z",
      "latestRun": {
        "id": "run_003",
        "status": "completed",
        "runNumber": 3
      }
    }
  ],
  "total": 5
}

---

Create campaign

POST /api/v1/runs

Creates a new campaign configuration. Does not trigger execution — use the trigger endpoint to start a run.

Request body

Field	Required	Type	Description
decisionFlowId	Yes	string	Decision flow to execute
segmentId	Yes	string	Customer segment to target
name	No	string	Campaign name (auto-generated if omitted)
description	No	string	Campaign purpose and notes
status	No	enum	draft, active, paused, archived. Default: draft
scheduleType	No	enum	manual, daily, weekly, monthly. Default: manual
scheduleDayOfWeek	No	integer	0=Sun..6=Sat (for weekly)
scheduleDayOfMonth	No	string	1-28 or last_working_day (for monthly)
scheduleTime	No	string	HH:mm format. Default: 09:00
scheduleTimezone	No	string	IANA timezone identifier (for example America/New_York). Default: UTC.
scheduleCron	No	string	Cron expression for custom schedules (e.g., 0 9 * * 1). Used when scheduleType does not cover the desired frequency.
frequencyCaps	No	object	{ maxTotalPerRun?, maxPerOffer?, maxPerChannel? }
fileConfig	No	object	{ format, columns[], includePersonalization, destination, s3Path? }
channelIds	No	string[]	Batch channel IDs to target (empty = all batch channels)

Example request

{
  "decisionFlowId": "df_001",
  "segmentId": "seg_001",
  "name": "Weekly High-Value Campaign",
  "status": "active",
  "scheduleType": "weekly",
  "scheduleDayOfWeek": 1,
  "scheduleTime": "09:00",
  "scheduleTimezone": "America/New_York",
  "frequencyCaps": { "maxTotalPerRun": 10000, "maxPerOffer": 500 },
  "fileConfig": {
    "format": "csv",
    "columns": ["customer_id", "offer_name", "channel", "score"],
    "destination": "download"
  }
}

Response 201

Returns the created campaign object.

---

Update campaign

PUT /api/v1/runs/:id

Updates campaign configuration. Accepts any combination of the following fields: name, description, status, scheduleType, scheduleDayOfWeek, scheduleDayOfMonth, scheduleTime, scheduleTimezone, scheduleCron, frequencyCaps, fileConfig, channelIds, decisionFlowId, segmentId.

Unlike most update endpoints, PUT allows changing decisionFlowId and segmentId to retarget a campaign to a different decision flow or customer segment.

---

Delete campaign

DELETE /api/v1/runs/:id

Deletes the campaign and all its runs. Requires admin role.

---

Get campaign detail

GET /api/v1/runs/:id

Returns the campaign config with the last 10 runs, resolved offer names in summaries, and enriched per-customer results.

---

Trigger a campaign run

POST /api/v1/runs/:id/campaign-runs

Creates and starts a new campaign run. The run is enqueued for processing by the worker tier, with inline fallback when the queue is unavailable.

Response 201

{
  "id": "crun_001",
  "campaignId": "camp_001",
  "runNumber": 4,
  "triggeredBy": "manual",
  "status": "pending",
  "createdAt": "2026-03-22T09:00:00.000Z"
}

---

List campaign runs

GET /api/v1/runs/:id/campaign-runs

Returns execution history for a campaign, ordered by run number descending (max 50).

---

Execute a run inline (background)

POST /api/v1/runs/execute-inline

Fire a run execution in the background and return immediately. The endpoint dispatches the batch executor without awaiting it — the HTTP response is sent before the batch starts producing output, and any per-run failure is recorded in the run’s status and logs rather than surfaced to the caller.

This endpoint is for inline triggers from a single-tenant dev environment or a backup path when the worker tier is degraded. Production triggering should use POST /api/v1/runs/:id/campaign-runs so the run gets a campaign-run record, retry semantics, and DLQ visibility.

Request Body

runId · string · required

Identifier of the run record that the executor will update with status, startedAt, and completedAt.

decisionFlowId · string · required

Decision flow to execute against.

segmentViewName · string · required

Customer-segment view name. The executor reads from this Postgres view to enumerate target customers.

Response

Status 200.

{
  "status": "executing",
  "runId": "run_42"
}

The response is sent the moment the executor is dispatched. The caller monitors progress by polling GET /api/v1/runs/:id.

Status codes

Code	When
200	Executor dispatched (returned immediately, before completion)
400	Missing runId, decisionFlowId, or segmentViewName
401 / 403	Caller is not authenticated, or not admin / editor

Roles

admin, editor.

Errors raised by the batch executor after the response is sent are logged but never surfaced to the caller. The run record’s status and error fields are the source of truth for outcome — poll GET /api/v1/runs/:id to see the final state.

---

Campaign statuses

Status	Description
draft	Created but not yet active
active	Live — scheduled runs execute automatically
paused	Temporarily disabled
archived	Retired, preserved for history

Run statuses

Status	Description
pending	Waiting for worker to pick up
running	Processing customers
completed	All customers processed
completed_with_errors	Finished but some deliveries failed
failed	Unrecoverable error

---

Role requirements

Method	Minimum role
GET (list/detail)	viewer
POST (create/trigger)	editor
PUT (update)	editor
DELETE	admin