Campaigns

CutX connects to ad platforms via OAuth and lets you launch campaigns with your generated assets.

List Campaigns

GET /api/campaigns?projectId=<uuid>&status=active&platform=meta
Authorization: Bearer <token>

Param	Type	Description
projectId	uuid	Filter by project
status	string	draft, active, paused, completed, error
platform	string	meta, tiktok, google

Response (200):

{
  "campaigns": [
    {
      "id": "uuid",
      "name": "Summer Sale Push",
      "platform": "meta",
      "status": "active",
      "objective": "sales",
      "budget_daily": 50.00,
      "start_date": "2026-03-10",
      "created_at": "2026-03-09T10:00:00Z"
    }
  ]
}

Create Campaign

POST /api/campaigns
Authorization: Bearer <token>
Content-Type: application/json

{
  "projectId": "uuid",
  "platform": "meta",
  "name": "Summer Sale Push",
  "objective": "sales",
  "budgetDaily": 50.00,
  "startDate": "2026-03-10",
  "endDate": "2026-03-31",
  "targeting": { "age_min": 25, "age_max": 45 },
  "assetIds": ["uuid", "uuid"]
}

Field	Type	Required	Options
projectId	uuid	Yes	—
platform	string	Yes	meta, tiktok, google
name	string	Yes	1-200 chars
objective	string	No	awareness, traffic, engagement, leads, sales
budgetDaily	number	No	Positive
budgetTotal	number	No	Positive
startDate	string	No	ISO date
endDate	string	No	ISO date
targeting	object	No	Platform-specific targeting
assetIds	uuid[]	No	Link generated assets

Update Campaign

PUT /api/campaigns/<id>
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "budgetDaily": 75.00,
  "status": "paused"
}

Launch Campaign

Pushes the campaign to the connected ad platform.

POST /api/campaigns/<id>/launch
Authorization: Bearer <token>

Requires an active platform connection (see below). The campaign transitions from draft to pending_review or active depending on the platform.

Delete Campaign

DELETE /api/campaigns/<id>
Authorization: Bearer <token>

Only draft campaigns can be deleted.

Platform Connections

Connect a Platform (OAuth)

GET /api/campaigns/connect/meta
Authorization: Bearer <token>

Redirects to the platform’s OAuth flow. After authorization:

GET /api/campaigns/connect/callback?code=<code>&state=<state>

List Connections

GET /api/campaigns/connections
Authorization: Bearer <token>

Response (200):

{
  "connections": [
    {
      "id": "uuid",
      "platform": "meta",
      "account_name": "My Business",
      "platform_account_id": "123456",
      "status": "active",
      "connected_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Ad Spend Fees

CutX charges a percentage fee on ad spend managed through the platform.

GET /api/campaigns/fees
Authorization: Bearer <token>

Tier	Fee
Default	6% of ad spend
Agency plan	4% of ad spend

Sync Spend Data

Pull latest spend data from connected platforms.

POST /api/campaigns/sync-spend
Authorization: Bearer <token>

Syncs the last 7 days of spend data and updates campaign_analytics.

Campaign Statuses

Status	Meaning
draft	Not yet launched
pending_review	Awaiting platform approval
active	Running
paused	Temporarily stopped
completed	Ended
rejected	Platform rejected
error	Sync or API error