Campaigns API

The Campaigns API is the programmatic interface to the Experiture campaign engine. It covers the full campaign lifecycle: create a campaign, configure its audience and content, run preflight checks, schedule or send it, and observe execution state and metrics.

Base URL: https://api.experiture.ai/public/v1

Authentication: All endpoints require a bearer token with the appropriate campaigns:* scope. See Authentication.

v1 scope. Public Campaigns v1 supports broadcast campaign type only. Unsupported campaign-type operations return a stable 409 TYPE_UNSUPPORTED; summary/object reads for an existing unsupported campaign return 409 SUMMARY_TYPE_UNSUPPORTED.

Endpoint Index

Campaign Object

Method	Path	Scope	Description
`POST`	`/campaigns`	`campaigns:create`	Create a new campaign
`GET`	`/campaigns`	`campaigns:read`	List campaigns with filtering and search
`GET`	`/campaigns/:id`	`campaigns:read`	Get full campaign object
`PATCH`	`/campaigns/:id`	`campaigns:update`	Update campaign metadata
`DELETE`	`/campaigns/:id`	`campaigns:delete`	Soft-delete a campaign
`POST`	`/campaigns/:id/archive`	`campaigns:delete`	Archive a campaign
`POST`	`/campaigns/:id/clone`	`campaigns:create`	Clone a campaign into a new draft

Configuration

Method	Path	Scope	Description
`PUT`	`/campaigns/:id/audience`	`campaigns:update`	Replace audience bindings
`PUT`	`/campaigns/:id/content`	`campaigns:update`	Replace content/template binding
`PUT`	`/campaigns/:id/schedule`	`campaigns:update`	Set schedule intent

Execution

Method	Path	Scope	Description
`POST`	`/campaigns/:id/preflight`	`campaigns:read`	Run pre-send validation checks
`POST`	`/campaigns/:id/schedule-jobs`	`campaigns:schedule`	Schedule the campaign send
`POST`	`/campaigns/:id/send-jobs`	`campaigns:send`	Send the campaign immediately

Observability

Method	Path	Scope	Description
`GET`	`/campaigns/:id/summary`	`campaigns:read`	Campaign setup summary
`GET`	`/campaigns/:id/status`	`campaigns:read`	Execution state and schedule
`GET`	`/campaigns/:id/metrics`	`analytics:read`	Execution pipeline counts

OAuth Scopes

Scope	Grants access to
`campaigns:read`	List, get, summary, status, preflight
`campaigns:create`	Create and clone campaigns
`campaigns:update`	Update metadata, audience, content, schedule
`campaigns:delete`	Soft-delete and archive
`campaigns:schedule`	Schedule a send via `POST /schedule-jobs`
`campaigns:send`	Trigger an immediate send via `POST /send-jobs`
`analytics:read`	Read execution metrics via `GET /metrics`

Grant only the scopes your integration needs. A reporting client needs only campaigns:read and analytics:read. A full authoring integration needs the full set.

Campaign Lifecycle

CREATE draft
    │
    ├─ PUT /audience      bind include/exclude segments
    ├─ PUT /content       assign published template
    ├─ PUT /schedule      set send mode (now / at)
    │
    ├─ POST /preflight    validate readiness
    │
    ├─ POST /schedule-jobs   schedule future send  ─┐
    └─ POST /send-jobs        send immediately       │
                                                     ▼
                              execution in progress / completed / failed
                                                     │
                              GET /status            observe execution state
                              GET /metrics           observe pipeline counts

Configuration steps (audience, content, schedule) can be done in any order and are only available while the campaign is in draft status. Once a send job is created, the campaign moves out of draft and configuration is locked.

Campaign Types & Channels

Supported campaign type (v1): broadcast

Supported channels:

Channel	Value
Email	`email`
SMS	`sms`
Push notification	`push`
Direct mail	`direct_mail`

Campaign Categories

Categories are a classification hint stored in campaign settings. The valid values are:

acquisition · nurturing · retention · reactivation · seasonal · product · event · template · updates · general

Invalid or omitted categories default to general. The category is also automatically added to the campaign's tags array.

Idempotency

Create, clone, schedule-jobs, and send-jobs support idempotent requests via the Idempotency-Key header (UUID v4). Duplicate requests with the same key and body return the cached response for 24 hours, preventing duplicate campaigns or duplicate sends on network retry.

Error Namespace

All Campaigns API errors use the JOURNEY_API.PUBLIC.CAMPAIGNS.* code namespace. See each endpoint page for the specific codes.