Console API

Ads campaigns

13 endpoints.

GET/api/v1/admin/businesses/{business_id}/ads/campaigns

List campaigns

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`status`	query	`string \| null`
`platform`	query	`string \| null`
`q`	query	`string \| null`
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 20
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_CampaignData__

Field Type Description

request_idrequired string

success true default true

datarequired

CampaignData[]

CampaignData[] fields

Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`status`required	`enum`	one of "draft", "active", "paused", "archived"
`platform`required	`enum`	one of "meta", "google"
`adSetCount`required	`integer`
`adUnitCount`required	`integer`
`budgetLabel`required	`string`
`adSets`	`AdSetData[]`	AdSetData[] fields Nested object (not expanded)
`costPerLead`	`number \| null`
`costPerLeadTrendPercent`	`integer \| null`
`reach`	`integer \| null`
`leads`	`integer \| null`
`targetingCity`	`string \| null`
`targetingRadiusMiles`	`integer \| null`
`budgetDailyUsd`	`integer \| null`
`isClientCreated`	`boolean \| null`
`currencyCode`	`string`	default "USD"
`leadFollowUpEnabled`	`boolean`	default false
`createdVia`	`enum`	one of "manual", "agent", "external" · default "manual"
`isExternallyManaged`	`boolean`	default false
`isManaged`	`boolean`	default true
`startedAt`	`string \| null`
`objective`	`string \| null`
`budgetLevel`	`string`	default "ad_set"
`dailyBudgetMinor`	`integer \| null`
`bidStrategy`	`string`	default "LOWEST_COST_WITHOUT_CAP"
`bidAmountMinor`	`integer \| null`
`externalPlatformCampaignId`	`string \| null`
`predecessorCampaignId`	`string (uuid) \| null`
`performanceFlag`	`CampaignListFlagSummary \| null`	CampaignListFlagSummary fields CampaignListFlagSummary (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns

Create a draft campaign

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonCampaignCreateBody

Field	Type	Description
`name`required	`string`
`platform`	`"meta"`	default "meta"
`objective`	`enum`	one of "OUTCOME_LEADS", "OUTCOME_TRAFFIC", "OUTCOME_SALES" · default "OUTCOME_LEADS"
`adsAccountId`	`string (uuid) \| null`
`leadFollowUpEnabled`	`boolean`	default true

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}

Get a campaign with embedded ad-sets and units

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`refreshFromMeta`	query	`boolean`	When true (default), pull this campaign's latest state from Meta and reconcile SOR before returning — the SAME full sync as the per-campaign Sync button, but due-gated (``ads_campaign_sync_min_interval_seconds``) so opening the page repeatedly doesn't hammer Meta. Set ``refreshFromMeta=false`` to read SOR only. default true
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}

Patch campaign name (status changes use dedicated verbs)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonCampaignPatchBody

Field	Type	Description
`name`	`string \| null`
`leadFollowUpEnabled`	`boolean \| null`
`isManaged`	`boolean \| null`
`objective`	`enum \| null`
`budgetLevel`	`enum \| null`
`dailyBudgetMinor`	`integer \| null`
`bidStrategy`	`enum \| null`
`bidAmountMinor`	`integer \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/archive

Archive locally + cascade soft-delete children

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/duplicate

Deep-copy campaign + sets + units as a new draft

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/launch

Validate + push to provider + set Active

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`Idempotency-Key`required	header	`string`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonCampaignLaunchBody

Field	Type	Description

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/pause

Pause on provider + locally

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/resume

Resume on provider + locally

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/{campaign_id}/sync

Pull this one campaign's latest state from Meta and return it

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`campaign_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignData`	CampaignData fields CampaignData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/agent

Trigger the campaign-creation agent (workflow engine)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string \| null`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonCampaignAgentTriggerBody

Field	Type	Description
`prompt`required	`string`	min length 1
`adsAccountId`	`string (uuid) \| null`
`campaignId`	`string (uuid) \| null`
`adSetId`	`string (uuid) \| null`
`unitId`	`string (uuid) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignAgentTriggerData_

Field Type Description

request_idrequired string

success true default true

datarequired

CampaignAgentTriggerData

CampaignAgentTriggerData fields

Field	Type	Description
`workflowRunId`required	`string`
`threadId`required	`string`
`status`required	`string`
`assistantReply`	`string`	default ""

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/ads/campaigns/agent/messages

List campaign-agent chat transcript

Return the persisted chat transcript for a thread.

The POST relay (``/agent/messages``) only returns the latest assistant reply per turn, so user-typed messages disappear from the FE on refresh. This GET reads the workflow-engine's ``thread_events`` (via control-plane ``/threads/{id}/detail``) and reduces them to the chat-message subset so the FE can render the full transcript and survive page reloads.

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`threadId`required	query	`string`
`limit`	query	`integer`	default 200
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ChatTranscriptData_

Field Type Description

request_idrequired string

success true default true

datarequired

ChatTranscriptData

ChatTranscriptData fields

Field	Type	Description
`threadId`required	`string`
`messages`required	`ChatMessageData[]`	ChatMessageData[] fields ChatMessageData (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/campaigns/agent/messages

Send a follow-up turn on an existing agent thread

Multi-turn relay so the FE doesn't need to talk to the router directly. The initial ``POST /campaigns/agent`` may return an empty ``workflowRunId``; keep POSTing here with the same ``threadId`` until a workflow run is started and a proposal widget appears.

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonCampaignAgentMessageBody

Field	Type	Description
`threadId`required	`string`	min length 1
`message`required	`string`	min length 1
`campaignId`	`string (uuid) \| null`
`adSetId`	`string (uuid) \| null`
`unitId`	`string (uuid) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_CampaignAgentTriggerData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`CampaignAgentTriggerData`	CampaignAgentTriggerData fields CampaignAgentTriggerData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.