Campaigns API Documentation

v1.0

Getting Started

The Campaigns API lets you create, manage, and monitor CTR campaigns programmatically. It supports all 9 campaign types with full feature parity to the UI wizard.

Authentication

Bearer token via API key generated in Settings → API Keys

Base URL

https://llkfxghqtntmhvpesqut.supabase.co/functions/v1/campaigns-api

Rate Limit

100 requests per 60-second window per user

Authentication

All requests require a valid API key passed as a Bearer token in the Authorization header.

Authorization: Bearer your-api-key-here

API keys are hashed with SHA-256 before storage. The raw key is shown only once at creation time. Generate keys in Settings → API Keys.

Endpoints

Campaign Types

AI Overview is Coming Soon and cannot be created, copied, or selected through the API or AI assistant. Other campaign types are listed below:

Type Value	Description	Required Config
website	Website CTR traffic — drives organic clicks to your site	keywords, geographic_targeting
gmb	Google My Business clicks — boosts local listing engagement	gmb_config, keywords
youtube	YouTube views & engagement — drives video interactions	youtube_config, keywords
brand_search	Brand search queries — increases branded search volume	brand_search_config
drive_emulation	GPS drive simulation — simulates directions to business	gmb_config (with startPointMode)
pogo_stick	Pogo-stick search behavior — click competitor then yours	keywords, geographic_targeting
directions	Google Maps directions — generates direction requests	gmb_config
referrer_traffic	Custom referrer traffic — drives visits from specific sources	referrer_pages

Fields Reference

Fields available when creating or updating campaigns via POST /campaigns.

Universal Fields

Field	Type	Required	Description	Example
name	string	Required	Campaign name. Max 255 characters, must be unique per user (case-insensitive).	"My Campaign"
type	string	Required	One of the 9 campaign types listed above.	"website"
target_url	string	Yes*	Target URL. Must be a valid URL. *Auto-generated for drive_emulation from gmb_config.	"https://example.com"
daily_click_target	number	Conditional	Number of clicks/actions per day. Must be >= 1. Required for most types.	50
budget	number	Optional	Maximum spend. Range: 0–10,000. Set 0 for unlimited. Defaults to 0.	500
keywords	string[]	Conditional	Search keywords. Required for website, gmb, youtube, pogo_stick types.	["seo tool", "best seo"]
geographic_targeting	object	Conditional	Geographic targeting. The "country" sub-field is required for all types except drive_emulation.	{ "country": "United States" }
click_target_timeframe	object	Optional	Controls click distribution over time.	{ "mode": "daily", "days": 7 }
active_weekdays	string[]	Optional	Which days the campaign runs. Subset of monday–sunday. Defaults to all 7 days.	["monday", "tuesday", "wednesday"]
timezone_config	object	Optional	Timezone and active hours configuration.	{ "timezone": "America/New_York", "distributionMode": "even", "activeHoursStart": 8, "activeHoursEnd": 22 }
demographic_targeting	object	Optional	Device type targeting.	{ "deviceType": "mobile" }

Module-Specific Fields

Field	Type	Required	Description	Example
businessName	string	Required	Name of the business on Google Maps.	"My Local Business"
businessAddress	string	Optional	Full street address of the business.	"123 Main St, City, State"
cid	string	Conditional	Google CID number. Either target_url or cid is required for GMB.	"12345678901234567"
placeId	string	Optional	Google Place ID.	"ChIJ..."
latitude	number	Optional	Business latitude coordinate.	40.7128
longitude	number	Optional	Business longitude coordinate.	-74.0060
country	string	Optional	Country of the business.	"United States"
searchAreaMode	string	Optional	How to define the search area.	"country" \| "exact_location" \| "radius"
searchAreaLat	number	Optional	Latitude for search area center (when using radius mode).	40.7128
searchAreaLng	number	Optional	Longitude for search area center.	-74.0060
searchAreaRadius	number	Optional	Radius in miles for the search area.	25
is_sab	boolean	Optional	Whether the business is a Service Area Business.	false
startPointMode	string	For drive_emulation	Where drives start from.	"random" \| "specific_address" \| "multiple_addresses"
startAddress	string	Optional	Start address when using specific_address mode.	"456 Start Ave"
multipleStartLocations	array	Optional	Multiple start points for drive emulation.	[{ "address": "...", "lat": 0, "lng": 0 }]

Validation Rules

The API enforces the same validation as the UI wizard. Key rules per type:

All Types

name required (max 255, unique per user), type must be valid, target_url must be valid URL, budget 0–10,000

website

keywords required unless referrer_pages.csvData has valid rows

gmb

gmb_config.businessName required, either target_url or gmb_config.cid required, keywords required

youtube

youtube_config.videoUrl required (valid YouTube URL), keywords required

ai_overview

Unavailable: creation, copies, imports and conversion to this type are rejected

drive_emulation

daily_click_target >= 1, gmb_config.businessName or businessAddress required, country required, startPointMode required

referrer_traffic

At least 1 valid source (CSV or manual), daily_click_target >= 1

brand_search

brand_search_config.brandName required

Server Defaults

Campaigns created via API automatically receive these defaults:

Field	Default Value
status	active
is_traffic_active	true
server_managed	true
real_browser_enabled	true
real_browser_quality_threshold	90
real_browser_budget_allocation	0.30
real_browser_max_sessions	5

Error Responses

All errors follow a consistent structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: ...",
    "details": {
      "validationErrors": [
        { "field": "name", "message": "Campaign name is required" }
      ]
    }
  },
  "meta": { "timestamp": "...", "version": "1.0", "request_id": "..." }
}

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
RATE_LIMIT_EXCEEDED	429	Too many requests (100/min limit)
VALIDATION_ERROR	400	Payload validation failed
CONFLICT	409	Duplicate campaign name
INSUFFICIENT_CREDITS	402	No available credits
NOT_FOUND	404	Campaign or endpoint not found
INTERNAL_ERROR	500	Unexpected server error

Quick Start

Sign up and go to Settings → API Keys to generate a key
Include the key as Authorization: Bearer YOUR_KEY
Set Content-Type: application/json for POST/PUT
Send requests to the base URL + endpoint path