Campaigns API

The Campaigns API allows you to create, manage, and optimize your advertising campaigns.

Create Campaign

Create a new advertising campaign.

POST /api/v1/campaigns

Headers

Content-Type: application/json
x-user-id: your-user-id

Request Body

{
  "name": "Tech Product Launch",
  "description": "Campaign for new AI productivity tool",
  "budget": 10000,
  "dailyBudget": 500,
  "targetAudience": {
    "keywords": ["AI", "productivity", "automation", "workflow"],
    "demographics": {
      "ageRange": "25-45",
      "interests": ["technology", "business", "productivity"]
    }
  },
  "creative": {
    "headline": "Revolutionize Your Workflow with AI",
    "description": "Boost productivity by 300% with our AI-powered automation tool",
    "callToAction": "Start Free Trial",
    "landingUrl": "https://myapp.com/signup"
  },
  "bidStrategy": "auto",
  "maxCpb": 2.50,
  "status": "active"
}

Response

{
  "id": "campaign-123",
  "name": "Tech Product Launch",
  "description": "Campaign for new AI productivity tool",
  "budget": 10000,
  "dailyBudget": 500,
  "spentBudget": 0,
  "targetAudience": {
    "keywords": ["AI", "productivity", "automation", "workflow"],
    "demographics": {
      "ageRange": "25-45",
      "interests": ["technology", "business", "productivity"]
    }
  },
  "creative": {
    "headline": "Revolutionize Your Workflow with AI",
    "description": "Boost productivity by 300% with our AI-powered automation tool",
    "callToAction": "Start Free Trial",
    "landingUrl": "https://myapp.com/signup"
  },
  "bidStrategy": "auto",
  "maxCpb": 2.50,
  "status": "active",
  "performance": {
    "impressions": 0,
    "clicks": 0,
    "conversions": 0,
    "ctr": 0,
    "averageCpb": 0
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Example

curl -X POST https://api.oncue.ad/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "name": "Tech Product Launch",
    "description": "Campaign for new AI productivity tool",
    "budget": 10000,
    "dailyBudget": 500,
    "targetAudience": {
      "keywords": ["AI", "productivity", "automation", "workflow"]
    },
    "creative": {
      "headline": "Revolutionize Your Workflow with AI",
      "description": "Boost productivity by 300% with our AI-powered automation tool",
      "callToAction": "Start Free Trial",
      "landingUrl": "https://myapp.com/signup"
    }
  }'

const response = await fetch('https://api.oncue.ad/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-user-id': 'user-123'
  },
  body: JSON.stringify({
    name: 'Tech Product Launch',
    description: 'Campaign for new AI productivity tool',
    budget: 10000,
    dailyBudget: 500,
    targetAudience: {
      keywords: ['AI', 'productivity', 'automation', 'workflow']
    },
    creative: {
      headline: 'Revolutionize Your Workflow with AI',
      description: 'Boost productivity by 300% with our AI-powered automation tool',
      callToAction: 'Start Free Trial',
      landingUrl: 'https://myapp.com/signup'
    }
  })
});

const campaign = await response.json();

List Campaigns

Get all campaigns for your account.

GET /api/v1/campaigns

Headers

x-user-id: your-user-id

Query Parameters

Parameter	Type	Description
`status`	string	Filter by campaign status (`active`, `paused`, `completed`)
`limit`	number	Number of campaigns to return (default: 20)
`offset`	number	Number of campaigns to skip (default: 0)

Response

[
  {
    "id": "campaign-123",
    "name": "Tech Product Launch",
    "description": "Campaign for new AI productivity tool",
    "budget": 10000,
    "dailyBudget": 500,
    "spentBudget": 1250,
    "status": "active",
    "performance": {
      "impressions": 15420,
      "clicks": 312,
      "conversions": 23,
      "ctr": 2.02,
      "averageCpb": 4.01
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T14:20:00Z"
  },
  {
    "id": "campaign-456",
    "name": "Brand Awareness Q1",
    "description": "Brand awareness campaign for Q1",
    "budget": 5000,
    "dailyBudget": 200,
    "spentBudget": 2100,
    "status": "paused",
    "performance": {
      "impressions": 8930,
      "clicks": 145,
      "conversions": 8,
      "ctr": 1.62,
      "averageCpb": 14.48
    },
    "createdAt": "2024-01-10T09:15:00Z",
    "updatedAt": "2024-01-14T16:45:00Z"
  }
]

Example

curl -X GET "https://api.oncue.ad/api/v1/campaigns?status=active&limit=10" \
  -H "x-user-id: user-123"

const response = await fetch('https://api.oncue.ad/api/v1/campaigns?status=active&limit=10', {
  headers: {
    'x-user-id': 'user-123'
  }
});

const campaigns = await response.json();

Get Campaign

Get details of a specific campaign.

GET /api/v1/campaigns/:id

Headers

x-user-id: your-user-id

Parameters

Parameter	Type	Description
`id`	string	The campaign ID

Response

{
  "id": "campaign-123",
  "name": "Tech Product Launch",
  "description": "Campaign for new AI productivity tool",
  "budget": 10000,
  "dailyBudget": 500,
  "spentBudget": 1250,
  "targetAudience": {
    "keywords": ["AI", "productivity", "automation", "workflow"],
    "demographics": {
      "ageRange": "25-45",
      "interests": ["technology", "business", "productivity"]
    }
  },
  "creative": {
    "headline": "Revolutionize Your Workflow with AI",
    "description": "Boost productivity by 300% with our AI-powered automation tool",
    "callToAction": "Start Free Trial",
    "landingUrl": "https://myapp.com/signup"
  },
  "bidStrategy": "auto",
  "maxCpb": 2.50,
  "status": "active",
  "performance": {
    "impressions": 15420,
    "clicks": 312,
    "conversions": 23,
    "ctr": 2.02,
    "averageCpb": 4.01
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T14:20:00Z"
}

Example

curl -X GET https://api.oncue.ad/api/v1/campaigns/campaign-123 \
  -H "x-user-id: user-123"

const response = await fetch('https://api.oncue.ad/api/v1/campaigns/campaign-123', {
  headers: {
    'x-user-id': 'user-123'
  }
});

const campaign = await response.json();

Update Campaign

Update an existing campaign.

PATCH /api/v1/campaigns/:id

Headers

Content-Type: application/json
x-user-id: your-user-id

Parameters

Parameter	Type	Description
`id`	string	The campaign ID

Request Body

{
  "name": "Updated Tech Product Launch",
  "dailyBudget": 750,
  "creative": {
    "headline": "Transform Your Workflow with AI",
    "description": "Boost productivity by 400% with our AI-powered automation tool"
  },
  "status": "paused"
}

Response

{
  "id": "campaign-123",
  "name": "Updated Tech Product Launch",
  "description": "Campaign for new AI productivity tool",
  "budget": 10000,
  "dailyBudget": 750,
  "spentBudget": 1250,
  "targetAudience": {
    "keywords": ["AI", "productivity", "automation", "workflow"],
    "demographics": {
      "ageRange": "25-45",
      "interests": ["technology", "business", "productivity"]
    }
  },
  "creative": {
    "headline": "Transform Your Workflow with AI",
    "description": "Boost productivity by 400% with our AI-powered automation tool",
    "callToAction": "Start Free Trial",
    "landingUrl": "https://myapp.com/signup"
  },
  "bidStrategy": "auto",
  "maxCpb": 2.50,
  "status": "paused",
  "performance": {
    "impressions": 15420,
    "clicks": 312,
    "conversions": 23,
    "ctr": 2.02,
    "averageCpb": 4.01
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T15:30:00Z"
}

Example

curl -X PATCH https://api.oncue.ad/api/v1/campaigns/campaign-123 \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "name": "Updated Tech Product Launch",
    "dailyBudget": 750,
    "status": "paused"
  }'

const response = await fetch('https://api.oncue.ad/api/v1/campaigns/campaign-123', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-user-id': 'user-123'
  },
  body: JSON.stringify({
    name: 'Updated Tech Product Launch',
    dailyBudget: 750,
    status: 'paused'
  })
});

const campaign = await response.json();

Delete Campaign

Delete a campaign. This action cannot be undone.

DELETE /api/v1/campaigns/:id

Headers

x-user-id: your-user-id

Parameters

Parameter	Type	Description
`id`	string	The campaign ID

Response

{
  "message": "Campaign deleted successfully"
}

Example

curl -X DELETE https://api.oncue.ad/api/v1/campaigns/campaign-123 \
  -H "x-user-id: user-123"

const response = await fetch('https://api.oncue.ad/api/v1/campaigns/campaign-123', {
  method: 'DELETE',
  headers: {
    'x-user-id': 'user-123'
  }
});

const result = await response.json();

Campaign Status Values

Status	Description
`draft`	Campaign is being created but not yet active
`active`	Campaign is live and serving ads
`paused`	Campaign is temporarily stopped
`completed`	Campaign has finished (budget spent or end date reached)
`cancelled`	Campaign has been cancelled

Bid Strategy Values

Strategy	Description
`auto`	Automatic bidding optimization
`manual`	Manual cost-per-bid setting
`target_cpa`	Target cost-per-acquisition
`maximize_clicks`	Maximize clicks within budget

Error Responses

Common error responses for campaign endpoints:

400 Bad Request

{
  "error": "Validation failed",
  "message": "Campaign name is required",
  "statusCode": 400
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "User ID is required",
  "statusCode": 401
}

404 Not Found

{
  "error": "Not found",
  "message": "Campaign not found",
  "statusCode": 404
}

409 Conflict

{
  "error": "Conflict",
  "message": "Campaign with this name already exists",
  "statusCode": 409
}

Create Campaign​

Headers​

Request Body​

Response​

Example​

List Campaigns​

Headers​

Query Parameters​

Response​

Example​

Get Campaign​

Headers​

Parameters​

Response​

Example​

Update Campaign​

Headers​

Parameters​

Request Body​

Response​

Example​

Delete Campaign​

Headers​

Parameters​

Response​

Example​

Campaign Status Values​

Bid Strategy Values​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

409 Conflict​

Create Campaign

Headers

Request Body

Response

Example

List Campaigns

Headers

Query Parameters

Response

Example

Get Campaign

Headers

Parameters

Response

Example

Update Campaign

Headers

Parameters

Request Body

Response

Example

Delete Campaign

Headers

Parameters

Response

Example

Campaign Status Values

Bid Strategy Values

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict