# Campaign Provisioning API

*/Software/Campaign_Provisioning_API*

## Solution Overview

The Campaign Provisioning API is a headless primitive that programmatically constructs, configures, and launches digital advertising campaigns across multiple ad networks simultaneously. It receives a JSON payload containing budget parameters, targeting rules, and creative asset URLs, and translates them into active ad sets on Meta, Google Ads, and TikTok. The output is an immediate array of live campaign IDs mapped back to the origin request, eliminating the need to manually navigate distinct ad manager interfaces.

Performance marketing agencies and internal growth teams integrate this API to automate large-scale creative testing and localized campaign deployment. Instead of media buyers spending hours duplicating ad sets and tweaking granular location targeting in web portals, developers script the deployment of hundreds of micro-campaigns in seconds. A built-in quarantine queue halts deployment if the requested daily budget exceeds pre-configured account limits, requiring a human manager's API key to force the launch.

Operating at the bottom of the marketing automation stack, the API acts as the execution layer for higher-level strategic software. It consumes generated ad copy and resized images from creative design agents, executing the mechanical setup process. Above it, autonomous bidding agents and cross-channel reporting dashboards consume the returned campaign IDs to track spend and adjust targets in real time.

## Headless Saas Data Model

**Entities**:
- Name: CampaignDeployment · Description: The root provision request defining campaign parameters and orchestrating cross-network launch
- Name: NetworkCampaign · Description: An active ad set initialized on a specific external advertising platform
- Name: CreativeAsset · Description: Media URLs and generated ad copy payloads attached to the deployment
- Name: TargetingRule · Description: Granular location or demographic parameters applied to the underlying network campaigns
- Name: QuarantineReview · Description: Holds halted deployments that exceed pre-configured workspace budget limits
- Name: Workspace · Description: Tenant grouping agency accounts and their hard spending limits
**Relations**:
- To: CampaignDeployment · From: Workspace · Label: scopes · Cardinality: one-to-many
- To: NetworkCampaign · From: CampaignDeployment · Label: provisions · Cardinality: one-to-many
- To: CreativeAsset · From: CampaignDeployment · Label: distributes · Cardinality: one-to-many
- To: TargetingRule · From: CampaignDeployment · Label: enforces · Cardinality: one-to-many
- To: QuarantineReview · From: CampaignDeployment · Label: triggers · Cardinality: one-to-one
**Tenant Anchor**: Workspace
**Primary Resource**: CampaignDeployment

## Api Definition

**Protocols**:
- REST
- SDK
- MCP
- Webhooks
**Consumed By**:
- [Autonomous Bidding Agent](/Agents/Autonomous_Bidding_Agent)
- [Creative Design Agent](/Agents/Creative_Design_Agent)
- [Media Buying Agent](/Agents/Media_Buying_Agent)
**Integrations**:
- [Meta Ads](/Products/Meta_Ads)
- [Google Ads](/Products/Google_Ads)
- [TikTok Ads](/Products/TikTok_Ads)
**Consumption Model**: An agent calls the MCP server to post a CampaignDeployment payload, then listens to webhooks to capture the provisioned externalCampaignIds for downstream bid optimization.
**Workflow Wrappers**:
- Name: Provision Omnichannel Campaign · Wraps: translates a single unified payload into active native ad sets across multiple ad networks
- Name: Resolve Budget Quarantine · Wraps: evaluates a halted deployment against workspace limits and accepts an override key to launch
- Name: Distribute Asset Variants · Wraps: pushes an array of creative URLs to all underlying network campaigns simultaneously

## Api Function Cascade

**Ai Role**: The headless API operates as fully autonomous stateless software, utilizing deterministic code to interact with ad networks and generative models to adapt text constraints end-to-end, relying on the calling software agent to manage exceptions or budget quarantines without human intervention.
**Cascade**:
- Kind: Code · Note: Receives the unified CampaignDeployment via MCP or REST API · Step: Ingest Deployment Payload · Verb: ingest · Realizes: Process Data Payload · Oversight: none
- Kind: Generative · Note: Transforms unified text to meet Meta, Google, and TikTok length constraints · Step: Adapt Platform Copy · Verb: adapt · Realizes: Adapt Digital Content · Oversight: none
- Kind: Code · Note: Pushes transformed payloads to underlying ad network APIs · Step: Provision Ad Sets · Verb: provision · Realizes: Create Advertising Campaign · Oversight: none
- Kind: Code · Note: Pushes creative URLs to all underlying network campaigns simultaneously · Step: Distribute Asset Links · Verb: distribute · Realizes: Distribute Digital Assets · Oversight: none
- Kind: Code · Note: Emits webhook with externalCampaignIds for downstream bidding agents · Step: Broadcast Provisioning State · Verb: emit · Realizes: Send System Notifications · Oversight: none
**Optimizes**:
- [Provisioning Success Rate](/Metrics/Provisioning_Success_Rate)
- [Cross-Network Sync Accuracy](/Metrics/Cross-Network_Sync_Accuracy)
- [API Response Latency](/Metrics/API_Response_Latency)
- [Time To Campaign Launch](/Metrics/Time_To_Campaign_Launch)

## Headless Saas Representative Offer

**Warranty**: Maintains a 99.9% API uptime SLA with automatic rollback for partial deployments and service credits issued for API downtime.
**Price Band**: ~$0.02 to $0.15 per successful campaign deployment or asset distribution API call
**Pricing Kind**: UsageMeter
**Deliverables**:
- Omnichannel campaign deployment execution
- Multi-network asset variant distribution
- Budget quarantine resolution capabilities
- Provisioning status webhook feeds
**Delivery Mode**: Self-serve API access is provisioned instantly upon authentication, allowing software agents to immediately consume the service via MCP or REST endpoints.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: Service Account
**Endpoints**:
- GET /campaign-deployments — list campaign deployments
- POST /campaign-deployments — create a campaign deployment
- GET /campaign-deployments/{id} — fetch a campaign deployment
- PATCH /campaign-deployments/{id} — update a campaign deployment
- POST /campaign-deployments/{id}/provision — execute the deployment orchestration across configured networks
- GET /campaign-deployments/{campaignDeploymentId}/network-campaigns — list network campaigns for a deployment
- POST /campaign-deployments/{campaignDeploymentId}/network-campaigns — initialize a network campaign ad set
- GET /campaign-deployments/{campaignDeploymentId}/network-campaigns/{id} — fetch a network campaign
- PATCH /campaign-deployments/{campaignDeploymentId}/network-campaigns/{id} — update a network campaign sync status
- GET /campaign-deployments/{campaignDeploymentId}/creative-assets — list creative assets attached to a deployment
- POST /campaign-deployments/{campaignDeploymentId}/creative-assets — attach a creative asset
- GET /campaign-deployments/{campaignDeploymentId}/creative-assets/{id} — fetch a creative asset
- PATCH /campaign-deployments/{campaignDeploymentId}/creative-assets/{id} — update a creative asset
- GET /campaign-deployments/{campaignDeploymentId}/targeting-rules — list targeting rules applied to a deployment
- POST /campaign-deployments/{campaignDeploymentId}/targeting-rules — add a targeting rule
- GET /campaign-deployments/{campaignDeploymentId}/targeting-rules/{id} — fetch a targeting rule
- PATCH /campaign-deployments/{campaignDeploymentId}/targeting-rules/{id} — update a targeting rule
- GET /campaign-deployments/{campaignDeploymentId}/quarantine-review — fetch the quarantine review for a halted deployment
- POST /campaign-deployments/{campaignDeploymentId}/quarantine-review/resolve — resolve a quarantine review to clear or reject the budget overage
- GET /workspaces — list workspaces
- POST /workspaces — create a workspace
- GET /workspaces/{id} — fetch a workspace
- PATCH /workspaces/{id} — update workspace budget limits and status
**Multitenancy**: Row-level isolation
**Webhook Events**:
- campaign_deployment.provisioned
- network_campaign.synced
- network_campaign.sync_failed
- quarantine_review.triggered
- quarantine_review.cleared

## Headless Saas Erd

```mermaid
erDiagram
    Workspace {
        UUID id PK "tenant key"
        VARCHAR name
        DECIMAL maxDailyBudget
        BOOLEAN isActive
    }
    CampaignDeployment {
        UUID id PK
        UUID workspaceId FK
        VARCHAR deploymentName
        DECIMAL totalDailyBudget
        VARCHAR deploymentStatus
        TIMESTAMP requestedAt
    }
    NetworkCampaign {
        UUID id PK
        UUID campaignDeploymentId FK
        VARCHAR networkType
        VARCHAR externalCampaignId
        DECIMAL networkBudget
        VARCHAR syncStatus
    }
    CreativeAsset {
        UUID id PK
        UUID campaignDeploymentId FK
        VARCHAR format
        VARCHAR assetUrl
        TEXT adCopyText
    }
    TargetingRule {
        UUID id PK
        UUID campaignDeploymentId FK
        VARCHAR ruleCategory
        JSONB parameters
        BOOLEAN isExclusion
    }
    QuarantineReview {
        UUID id PK
        UUID campaignDeploymentId FK
        DECIMAL budgetOverage
        VARCHAR reviewerApiKey
        VARCHAR resolution
        TIMESTAMP clearedAt
    }
    Workspace ||--o{ CampaignDeployment : scopes
    CampaignDeployment ||--o{ NetworkCampaign : provisions
    CampaignDeployment ||--o{ CreativeAsset : distributes
    CampaignDeployment ||--o{ TargetingRule : enforces
    CampaignDeployment ||--|| QuarantineReview : triggers
```

## Neighborhood

### Composed into

- [Priya](/Agents/Priya) — composes · Agents

### Optimizes

- [Time To Campaign Launch](/Metrics/Time_To_Campaign_Launch) — optimizes · Metrics
- [API Response Latency](/Metrics/API_Response_Latency) — optimizes · Metrics
- [Cross-Network Sync Accuracy](/Metrics/Cross-Network_Sync_Accuracy) — optimizes · Metrics
- [Provisioning Success Rate](/Metrics/Provisioning_Success_Rate) — optimizes · Metrics

### What it uses

- [TikTok Ads](/Products/TikTok_Ads) — uses · Products
- [Google Ads](/Software/Google_Ads) — uses · Software
- [Meta Ads](/Products/Meta_Ads) — uses · Products

### Who consumes this

- [Autonomous Bidding Agent](/Agents/Autonomous_Bidding_Agent) — consumed by · Agents
- [Creative Design Agent](/Agents/Creative_Design_Agent) — consumed by · Agents
- [Media Buying Agent](/Agents/Media_Buying_Agent) — consumed by · Agents

### Similar Agents

- [Declarative Provisioning API](/Agents/Declarative_Provisioning_API) — similar · Agents

### Similar Customers

- [Specialized performance agencies](/Customers/Specialized_performance_agencies) — similar · Customers

### Similar Software

- [Audience Intelligence Software](/Metrics/Audience_Reach/Software/Audience_Intelligence_Software) — similar · Software

### Similar Startups

- [Allocateaura](/Startups/Allocateaura) — similar · Startups
- [Abray](/Startups/Abray) — similar · Startups
- [Advargin](/Startups/Advargin) — similar · Startups
- [Abhorring](/Startups/Abhorring) — similar · Startups
- [Cascadepace](/Startups/Cascadepace) — similar · Startups
- [Advead](/Startups/Advead) — similar · Startups
- [Blossirector](/Startups/Blossirector) — similar · Startups
- [Allocationoptimize](/Startups/Allocationoptimize) — similar · Startups
- [Advalign](/Startups/Advalign) — similar · Startups
- [Distributioncamp](/Startups/Distributioncamp) — similar · Startups
- [Chasemill](/Startups/Chasemill) — similar · Startups
- [Wavesuite](/Startups/Wavesuite) — similar · Startups
- [Valar](/Startups/Valar) — similar · Startups

### Similar Resources

- [Ad network APIs](/Resources/Ad_network_APIs) — similar · Resources
- [Media buyer networks](/Resources/Media_buyer_networks) — similar · Resources

### Similar Partners

- [Digital ad platforms](/Partners/Digital_ad_platforms) — similar · Partners
- [Media buying platforms](/Partners/Media_buying_platforms) — similar · Partners