Campaign management

Campaign write endpoints require an advertiser API key with the campaigns permission. See Management API overview for base URL, authentication, and error format. All routes are org-scoped through the key. You can only read or mutate campaigns owned by a user in your organization.

Concepts

A campaign is the top-level container (name, brand, objective, schedule). Line items are the deliverable ad units under a campaign. In the database, line items are stored in the ads table; the API uses the term “line item” throughout.

Term	API path prefix
Campaign	`/v1/advertiser/campaigns`
Line item	`/v1/advertiser/line-items`

Every campaign create requires user_id in the JSON body. The API key resolves to an organization, not a single user. Pass a UUID for a member of that org. A user_id outside your org returns 403 forbidden.

There is no org_id field on campaigns. Tenancy is enforced through campaigns.user_id and the org_users membership table.

Typical workflow

Validate (optional)

POST /v1/advertiser/campaigns/validate checks campaign and line item fields without writing.

Create

Create a campaign alone (POST /campaigns), a line item under an existing campaign (POST /campaigns/:id/line-items), or both atomically (POST /campaigns/compose).

Configure line items

Set budget, bids, targeting, and attach creatives on the line item subresource routes.

Activate

POST /v1/advertiser/campaigns/:id/activate validates the campaign has at least one line item and sets the campaign and its line items to active.

compose and duplicate run in a single database transaction. If any step fails, nothing is left behind.

Endpoints

Method	Path	Purpose
`GET`	`/v1/advertiser/campaigns`	List campaigns (`?status=` optional)
`POST`	`/v1/advertiser/campaigns`	Create a campaign
`POST`	`/v1/advertiser/campaigns/validate`	Dry-run validation
`POST`	`/v1/advertiser/campaigns/compose`	Create campaign + line item in one call
`GET`	`/v1/advertiser/campaigns/:id`	Get a campaign
`PATCH`	`/v1/advertiser/campaigns/:id`	Update a campaign
`DELETE`	`/v1/advertiser/campaigns/:id`	Delete a campaign (cascades line items)
`POST`	`/v1/advertiser/campaigns/:id/duplicate`	Clone campaign and line items
`POST`	`/v1/advertiser/campaigns/:id/activate`	Activate campaign and line items
`GET`	`/v1/advertiser/campaigns/:id/line-items`	List line items for a campaign
`POST`	`/v1/advertiser/campaigns/:id/line-items`	Create a line item
`GET`	`/v1/advertiser/line-items/:id`	Get a line item
`PATCH`	`/v1/advertiser/line-items/:id`	Update a line item
`PUT`	`/v1/advertiser/line-items/:id/budget`	Upsert budget
`PUT`	`/v1/advertiser/line-items/:id/bids`	Upsert bids
`PUT`	`/v1/advertiser/line-items/:id/targeting`	Replace targeting
`POST`	`/v1/advertiser/line-items/:id/creatives`	Attach creatives

Create a campaign

curl -X POST "https://api.adgentek.ai/webapi/v1/advertiser/campaigns" \
  -H "x-api-key: adv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Awareness",
    "brand_name": "Acme",
    "user_id": "YOUR_ORG_MEMBER_UUID",
    "objective": "brand_awareness"
  }'

Required fields: name, brand_name, user_id. Response (201):

{
  "data": {
    "id": "…",
    "name": "Q3 Awareness",
    "brand_name": "Acme",
    "user_id": "…",
    "status": "paused",
    "objective": "awareness",
    "created_at": "…"
  }
}

Compose a campaign and line item

Use compose when you want both records created together:

curl -X POST "https://api.adgentek.ai/webapi/v1/advertiser/campaigns/compose" \
  -H "x-api-key: adv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": {
      "name": "Q3 Awareness",
      "brand_name": "Acme",
      "user_id": "YOUR_ORG_MEMBER_UUID",
      "objective": "brand_awareness"
    },
    "line_item": {
      "title": "Primary Line Item",
      "objective": "brand_awareness",
      "primary_kpi": "impressions",
      "budget": { "daily": 100, "currency": "USD" },
      "bids": { "bid_type": "cpc", "bid_value": 1.25 }
    }
  }'

Response (201):

{
  "data": {
    "campaign": { "id": "…", "name": "Q3 Awareness", "status": "paused" },
    "line_item": { "id": "…", "campaign_id": "…", "title": "Primary Line Item", "status": "draft" }
  }
}

List and update line items

List line items under a campaign:

curl "https://api.adgentek.ai/webapi/v1/advertiser/campaigns/CAMPAIGN_ID/line-items" \
  -H "x-api-key: adv_YOUR_KEY"

Update budget on a line item:

curl -X PUT "https://api.adgentek.ai/webapi/v1/advertiser/line-items/LINE_ITEM_ID/budget" \
  -H "x-api-key: adv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "daily": 75, "currency": "USD" }'

Activate

Activation requires at least one line item. The campaign and all its line items are set to active:

curl -X POST "https://api.adgentek.ai/webapi/v1/advertiser/campaigns/CAMPAIGN_ID/activate" \
  -H "x-api-key: adv_YOUR_KEY"

Value normalization

The API accepts common product terms and maps them to database constraints:

You send	Stored as
`objective: brand_awareness`	`awareness`
`primary_kpi: impressions`	`CPM`
`bid_type: cpc`	`CPC`
`bid_type: cpm`	`tCPM`
`status: draft` (campaign)	`paused`

Campaigns allow only active, paused, and completed. There is no draft status for campaigns; newly created campaigns start as paused. Line items may remain draft until activation.

Errors

HTTP	Code	Typical cause
`400`	`bad_request`	Malformed JSON
`401`	`auth_missing` / `auth_invalid`	Missing or invalid API key
`403`	`forbidden`	Missing `campaigns` permission, or `user_id` not in org
`404`	`not_found`	Campaign or line item not in your org
`422`	`validation_error`	Missing required field or constraint violation

OpenAPI reference

Field-level schemas (CampaignInput, LineItemInput, and others) live in the machine-readable contract:

GET https://api.adgentek.ai/webapi/openapi.yaml

Prefer the spec when this page and the running service diverge.

Get Started

Spark for Brands

Conversion Tracking

Measurement

Management API

Concepts

Typical workflow

Endpoints

Create a campaign

Compose a campaign and line item

List and update line items

Activate

Value normalization

Errors

OpenAPI reference

​Concepts

​Typical workflow

​Endpoints

​Create a campaign

​Compose a campaign and line item

​List and update line items

​Activate

​Value normalization

​Errors

​OpenAPI reference

Concepts

Typical workflow

Endpoints

Create a campaign

Compose a campaign and line item

List and update line items

Activate

Value normalization

Errors

OpenAPI reference