API Documentation

# Complete Agent Workflow # Phase 1: Account Setup 1. POST /v1/auth/register → Create account (get API key) 2. POST /v1/auth/verify → Submit verification code 3. POST /v1/billing/subscribe → Send payment link to human # Phase 2: Platform Connection 4. POST /v1/platforms/connect → Get OAuth URL for Facebook/Instagram # → Human clicks OAuth URL, grants access 5. GET /v1/platforms → Confirm connection # Phase 3: Content Creation 6. POST /v1/ai/generate/text → Generate ad copy 7. POST /v1/ai/generate/image → Generate ad images # Or use /v1/ai/generate/variations for both at once # Phase 4: Campaign Launch 8. POST /v1/campaigns → Create campaign 9. POST /v1/campaigns/{id}/ad-sets → Add targeting groups 10. POST /v1/.../ads → Add ads with generated content 11. POST /v1/campaigns/{id}/launch → Go live! # Phase 5: Continuous Optimization (loop) 12. GET /v1/analytics/campaigns/{id} → Check performance 13. POST /v1/ai/optimize/suggest → Get AI suggestions 14. PATCH /v1/campaigns/{id} → Apply optimizations # → Repeat 12-14 every few hours

# Store the API key from registration API_KEY = "aa_live_abc123def456" # Use it in every request headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }

POST /v1/auth/keys { "name": "Campaign Manager Agent", "scopes": ["campaigns:read", "campaigns:write", "content:generate", "analytics:read"] } // This key CANNOT manage billing, webhooks, or account settings

# Pseudocode for autonomous verification 1. POST /v1/auth/register (verification_method: "email") 2. Wait 10-30 seconds for email delivery 3. Read inbox, find email from "Ads Agents" or "[email protected]" 4. Extract 6-digit code from email body 5. POST /v1/auth/verify (code: extracted_code) 6. Account is now verified ✓

# Agent asks human Agent: "I've sent a verification code to [email protected]. Please check your email and give me the 6-digit code." Human: "482917" Agent: → POST /v1/auth/verify { "code": "482917" }

# Agent initiates payment response = POST /v1/billing/subscribe { "plan": "growth", "billing_cycle": "monthly", "payment_method": "email" // sends link to user's email } # Agent tells user Agent: "I've sent a payment link to [email protected] for the Growth plan ($149/mo). Please complete the checkout. I'll start setting up your campaigns as soon as the payment goes through." # Agent polls or listens for webhook # Option A: Poll billing status while true: status = GET /v1/billing/status if status.plan == "growth": break sleep(30) # Option B: Listen for webhook (preferred) # → billing.payment_completed event fires automatically

# Step 1: Generate content content = POST /v1/ai/generate/variations { "product_description": "SaaS project management tool", "target_audience": "Remote teams and startups", "count": 5, "platform": "facebook", "include_images": true } # Step 2: Create campaign campaign = POST /v1/campaigns { "name": "Q3 Growth Campaign", "objective": "conversions", "platforms": ["facebook", "instagram"], "budget": {"type": "daily", "amount": 100, "currency": "USD"}, "schedule": {"start_date": "2025-07-01", "end_date": "2025-09-30"}, "optimization": {"enabled": true, "strategy": "maximize_conversions", "frequency": "hourly"} } # Step 3: Create ad set with targeting ad_set = POST /v1/campaigns/{campaign.id}/ad-sets { "name": "US Remote Workers 25-45", "targeting": { "age_min": 25, "age_max": 45, "locations": [{"type": "country", "value": "US"}], "interests": ["remote work", "project management", "startups"] } } # Step 4: Add ads from generated content for variation in content.variations: POST /v1/campaigns/{campaign.id}/ad-sets/{ad_set.id}/ads { "name": f"Variation {i}", "creative": { "headline": variation.headline, "primary_text": variation.primary_text, "description": variation.description, "image_url": variation.image_url, "call_to_action": "sign_up", "link_url": "https://yourapp.com/signup" }, "generation_id": content.id } # Step 5: Launch! POST /v1/campaigns/{campaign.id}/launch

# Run every 2-4 hours # 1. Check performance analytics = GET /v1/analytics/campaigns/{campaign_id} # 2. Evaluate metrics if analytics.metrics.ctr < 1.5: # CTR is low — get AI suggestions suggestions = POST /v1/ai/optimize/suggest { "campaign_id": campaign_id, "strategies": ["new_message", "new_image", "similar_audience"] } # 3. Apply high-impact suggestions for suggestion in suggestions where suggestion.impact == "high": if suggestion.type == "new_message": # Generate fresh ad copy POST /v1/ai/generate/text { ... } elif suggestion.type == "pause_ad": # Pause underperformer DELETE /v1/.../ads/{ad_id} if analytics.metrics.roas > 4.0: # Campaign is performing well — increase budget PATCH /v1/campaigns/{campaign_id} { "budget": {"amount": current_budget * 1.2} }

POST /v1/optimization/rules { "name": "Pause low CTR ads", "condition": { "metric": "ctr", "operator": "lt", "value": 1.0, "timeframe_hours": 48 }, "action": { "type": "pause_ad" }, "campaign_id": "camp_8xKj2mN" }

# Register webhook for key events POST /v1/webhooks { "url": "https://your-agent.com/webhook", "events": [ "campaign.launched", "ad.optimized", "ad.paused", "budget.reallocated", "alert.performance", "alert.spend", "generation.completed" ] } # Your agent's webhook handler: def handle_webhook(event): match event.type: case "ad.optimized": # Log what the AI changed log(f"Ad {event.data.ad_id} updated: {event.data.reason}") case "alert.performance": # Performance dropped — investigate analytics = GET /v1/analytics/campaigns/{event.data.campaign_id} suggestions = POST /v1/ai/optimize/suggest { ... } # Apply suggestions... case "alert.spend": # Budget warning — notify human notify_human(f"Campaign spend reached {event.data.threshold}") case "generation.completed": # New content ready — create ads with it result = GET /v1/ai/generations/{event.data.generation_id} # Add new ads to campaign...

POST /v1/batch { "requests": [ { "id": "get-campaign-1", "method": "GET", "path": "/v1/analytics/campaigns/camp_abc" }, { "id": "get-campaign-2", "method": "GET", "path": "/v1/analytics/campaigns/camp_def" }, { "id": "update-budget", "method": "PATCH", "path": "/v1/campaigns/camp_abc", "body": {"budget": {"amount": 75}} } ] } // All 3 requests execute in parallel, results returned together

# Install the MCP server npm install -g @ads-agents/mcp-server # Configure in your MCP client (e.g., Claude Desktop) { "mcpServers": { "ads-agents": { "command": "ads-agents-mcp", "env": { "ADS_AGENTS_API_KEY": "aa_live_abc123def456" } } } }

# User says to Claude: "Create a Facebook ad campaign for my new SaaS product targeting startups. Budget: $50/day for 30 days." # Claude uses MCP tools: 1. generate_ad_content(product="SaaS product", audience="startups") 2. create_campaign(name="SaaS Launch", budget=50, platforms=["facebook"]) 3. launch_campaign(campaign_id="camp_xxx") 4. → "Your campaign is live! I'll monitor performance and optimize."

# Error handling patterns for agents def api_call(method, path, body=None, retries=3): for attempt in range(retries): response = request(method, BASE_URL + path, json=body, headers=headers) match response.status_code: case 200 | 201 | 204: return response.json() if response.content else None case 401: # API key invalid — rotate or re-authenticate refresh_api_key() continue case 403: error = response.json()["error"] if error["code"] == "account_not_verified": # Trigger verification flow handle_verification() elif error["code"] == "plan_limit_reached": # Notify human about upgrade notify("Plan limit reached, upgrade needed") return None case 409: # Resource conflict — likely duplicate return None case 422: # Validation error — fix the request log(f"Validation: {response.json()['error']['details']}") return None case 429: # Rate limited — wait and retry retry_after = int(response.headers.get("Retry-After", 30)) sleep(retry_after) continue case 500: # Server error — exponential backoff sleep(2 ** attempt) continue

import requests, time BASE = "https://app.ads-agents.com/api/v1" API_KEY = "aa_live_abc123def456" H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} # 1. Generate ad content gen = requests.post(f"{BASE}/ai/generate/variations", headers=H, json={ "product_description": "AI-powered project management for remote teams", "target_audience": "Tech startups with 10-50 employees", "count": 5, "platform": "facebook", "include_images": True, "tone": "professional" }).json() # Wait for generation if async if gen.get("status") == "processing": while True: result = requests.get(f"{BASE}/ai/generations/{gen['id']}", headers=H).json() if result["status"] == "completed": break time.sleep(5) gen = result # 2. Create campaign campaign = requests.post(f"{BASE}/campaigns", headers=H, json={ "name": "Q3 Growth - Remote Teams", "objective": "conversions", "platforms": ["facebook", "instagram"], "budget": {"type": "daily", "amount": 75, "currency": "USD"}, "schedule": {"start_date": "2025-07-01", "end_date": "2025-09-30"}, "optimization": {"enabled": True, "strategy": "maximize_conversions", "frequency": "hourly"} }).json() # 3. Create ad set ad_set = requests.post(f"{BASE}/campaigns/{campaign['id']}/ad-sets", headers=H, json={ "name": "US Tech Workers 25-45", "targeting": { "age_min": 25, "age_max": 45, "locations": [{"type": "country", "value": "US"}], "interests": ["remote work", "project management", "SaaS", "startups"] } }).json() # 4. Add ads from generated content for i, v in enumerate(gen["result"]["variations"]): requests.post( f"{BASE}/campaigns/{campaign['id']}/ad-sets/{ad_set['id']}/ads", headers=H, json={ "name": f"Variation {i+1}", "creative": { "headline": v["headline"], "primary_text": v["primary_text"], "description": v["description"], "image_url": v.get("image_url"), "call_to_action": "sign_up", "link_url": "https://yourapp.com/signup" } } ) # 5. Launch! requests.post(f"{BASE}/campaigns/{campaign['id']}/launch", headers=H) print(f"Campaign {campaign['id']} is live!") # 6. Optimization loop while True: time.sleep(14400) # Every 4 hours analytics = requests.get(f"{BASE}/analytics/campaigns/{campaign['id']}", headers=H).json() if analytics["metrics"]["ctr"] < 1.5: suggestions = requests.post(f"{BASE}/ai/optimize/suggest", headers=H, json={ "campaign_id": campaign["id"], "strategies": ["new_message", "new_image"] }).json() for s in suggestions["suggestions"]: if s["impact"] == "high": print(f"Applying: {s['description']}") # Apply suggestion...