Internal API

Ads workflow engine

18 endpoints.

POST/api/v1/internal/workflow-engine/ads/archive-campaign

Archive Campaign

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolArchiveCampaignBody

Field	Type	Description
`businessId`required	`string (uuid)`
`campaignId`required	`string (uuid)`
`userConfirmed`	`boolean`	default false

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field Type Description

request_idrequired string

success true default true

datarequired object

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/internal/workflow-engine/ads/create-ad-unit

Create Ad Unit

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolCreateAdUnitBody

Field	Type	Description
`businessId`required	`string (uuid)`
`adSetId`required	`string (uuid)`
`photoId`required	`string (uuid)`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/create-refresh-draft

Create Refresh Draft

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolCreateRefreshDraftBody

Field	Type	Description
`businessId`required	`string (uuid)`
`recommendationId`required	`string (uuid)`
`action`required	`enum`	one of "refresh_creative", "refresh_audience"
`photoIds`required	`string (uuid)[]`	min items 1 string (uuid)[] fields
`adCopy`	`string \| null`
`headline`	`string \| null`
`targetingAdjustments`	`object \| null`
`rationale`	`string \| null`
`mediaBrief`	`object \| null`
`mediaCandidates`	`object[] \| null`	object[] \| null fields
`mediaReview`	`object \| null`
`workflowRunId`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/disable-all-units

Disable All Units

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolDisableAllUnitsBody

Field	Type	Description
`businessId`required	`string (uuid)`
`adSetId`required	`string (uuid)`
`userConfirmed`	`boolean`	default false

Responses

204Successful Response

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

Error bodies: ErrorResponse. See Errors.

POST/api/v1/internal/workflow-engine/ads/draft-proposal

Non-mutating: enrich the workflow-engine's router-extracted hints into a complete proposal (name, ad copy, headline, address, lat/lng, page, currency) so the ``ADS_CAMPAIGN_PROPOSAL`` widget renders something the user can actually approve. The temporal worker calls this just before parking at ``bp_ads_creator_proposal`` and stuffs the response into ``extracted_data.plan``.

Parameters

Name	In	Type	Description
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolDraftCampaignProposalBody

Field	Type	Description
`businessId`required	`string (uuid)`
`promotion`	`string \| null`
`dailyBudgetMinor`	`integer \| null`
`radiusMeters`	`integer \| null`
`objective`	`string \| null`
`adsAccountId`	`string (uuid) \| null`
`addressLine`	`string \| null`
`attachedPhotoIds`	`string[] \| null`	string[] \| null fields
`adSets`	`object[] \| null`	object[] \| null fields
`businessContext`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/generate-refresh-plan

Generate Refresh Plan

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolGenerateRefreshPlanBody

Field	Type	Description
`businessId`required	`string (uuid)`
`entityType`required	`enum`	one of "campaign", "ad_set", "ad_unit"
`entityId`required	`string (uuid)`
`recommendationId`	`string (uuid) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/get-campaign

Get Campaign

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolGetCampaignBody

Field	Type	Description
`businessId`required	`string (uuid)`
`campaignId`required	`string (uuid)`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/get-insight-tile

Get Insight Tile

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolGetInsightTileBody

Field	Type	Description
`businessId`required	`string (uuid)`
`entityType`required	`enum`	one of "campaign", "ad_set", "ad_unit"
`entityId`required	`string (uuid)`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/get-refresh-context

Get Refresh Context

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolGetRefreshContextBody

Field	Type	Description
`businessId`required	`string (uuid)`
`entityType`required	`enum`	one of "campaign", "ad_set", "ad_unit"
`entityId`required	`string (uuid)`
`recommendationId`	`string (uuid) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/list-ad-sets

List Ad Sets

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolListAdSetsBody

Field	Type	Description
`businessId`required	`string (uuid)`
`campaignId`required	`string (uuid)`

Responses

200Successful Response

application/jsonSuccessResponse_list_dict__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object[]`	object[] fields
`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/internal/workflow-engine/ads/list-campaigns

List Campaigns

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolListCampaignsBody

Field	Type	Description
`businessId`required	`string (uuid)`
`status`	`string \| null`
`q`	`string \| null`
`limit`	`integer`	default 20 · min 1 · max 100

Responses

200Successful Response

application/jsonSuccessResponse_list_dict__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object[]`	object[] fields
`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/internal/workflow-engine/ads/propose-campaign

Propose Campaign

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolProposeCampaignBody

Field	Type	Description
`businessId`required	`string (uuid)`
`plan`required	`object`
`actorUserId`	`string (uuid) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/review-refresh-media

Review Refresh Media

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolReviewRefreshMediaBody

Field	Type	Description
`businessId`required	`string (uuid)`
`mediaBrief`	`object \| null`
`candidates`required	`object[]`	min items 1 object[] fields

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/toggle-unit

Toggle Unit

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolToggleUnitBody

Field	Type	Description
`businessId`required	`string (uuid)`
`unitId`required	`string (uuid)`
`enabled`required	`boolean`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/update-ad-set

Update Ad Set

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolUpdateAdSetBody

Field	Type	Description
`businessId`required	`string (uuid)`
`adSetId`required	`string (uuid)`
`patch`required	`object`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/update-ad-unit

Update Ad Unit

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolUpdateAdUnitBody

Field	Type	Description
`businessId`required	`string (uuid)`
`unitId`required	`string (uuid)`
`patch`required	`object`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/update-campaign

Update Campaign

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolUpdateCampaignBody

Field	Type	Description
`businessId`required	`string (uuid)`
`campaignId`required	`string (uuid)`
`patch`required	`object`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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/internal/workflow-engine/ads/update-refresh-status

Update Refresh Status

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	`string`
`x-internal-api-key`	header	`string \| null`

Request bodyrequired

application/jsonToolUpdateRefreshStatusBody

Field	Type	Description
`businessId`required	`string (uuid)`
`recommendationId`required	`string (uuid)`
`status`required	`enum`	one of "failed", "generating", "superseded"
`workflowRunId`	`string \| null`
`failureCode`	`string \| null`
`errorMessage`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`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.