Adspirer REST API Reference

Adspirer REST API

178 tools across Google Ads, Meta, LinkedIn, TikTok, Monitoring, and Audit — callable from any HTTP client. Designed for n8n, Zapier, Make, Python, Node.js, curl, and any language with an HTTP library.

Quickstart

curl -X POST https://api.adspirer.ai/api/v1/tools/list_connected_accounts/execute \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{}}'

Every request takes the same shape: POST /api/v1/tools/<tool_name>/execute with {"arguments": {...}} as the body. Every response is JSON — no streaming.

Core concepts

Authentication: Bearer API key (sk_live_...). Generate at adspirer.ai/keys.

Idempotency: Pass Idempotency-Key: <uuid> on writes to make retries safe.

Quota: Each plan has a monthly tool-call allowance; current usage is attached to every response.

Multi-account: Customers with multiple connected ad accounts must pass ad_account_id / customer_id / advertiser_id / account_id explicitly.

Google Ads (51 tools)

add_callout_extensions ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_demandgen_ad_group ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_keywords ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_negative_keywords ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_pmax_audience_signal ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_pmax_search_themes ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_sitelinks ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

add_structured_snippets ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

analyze_search_terms 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

analyze_wasted_spend 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

create_ad ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

create_demandgen_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

create_pmax_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

create_search_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

create_youtube_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

discover_existing_assets 📖 🔍 Discover existing assets in the Google Ads account (images, sitelinks, callouts, structured snippets)

explain_performance_anomaly 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_benchmark_context 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_business_profile 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_campaign_performance 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_campaign_structure 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_campaign_targeting 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_pmax_audience_signals 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_pmax_search_themes 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

get_usage_status 📖 Get your current usage status with interactive quota widget

help_user_upload 📖 Show user instructions for uploading images to postimages

infer_business_profile ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

list_campaign_extensions 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

list_campaigns 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

optimize_budget_allocation 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

pause_ad ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

pause_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

remove_keywords ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

remove_negative_keywords ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

remove_pmax_audience_signal ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

remove_pmax_search_themes ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

research_keywords 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

resume_ad ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

resume_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

save_business_profile ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

search_audiences 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

select_google_campaign_type 📖 **USE THIS TOOL FIRST WHEN:** User wants to create a Google Ads campaign but hasn't specified the campaign type (Search, Performance Max, or YouTube)

suggest_ad_content 📖 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_ad_content ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_ad_descriptions ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_ad_headlines ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_bid_strategy ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_campaign ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

update_keyword ✏️ 🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the u

validate_and_prepare_assets ✏️ 🔄 LONG-RUNNING TOOL: Validates multiple images from URLs for Performance Max campaigns

validate_video 📖 Validate video for ad campaigns (unified tool for all platforms)

LinkedIn Ads (45 tools)

add_linkedin_campaign_to_group ✏️ **USE THIS TOOL WHEN:** User wants to add a new campaign with DIFFERENT targeting/audience to an EXISTING campaign group

add_linkedin_carousel_creative ✏️ User wants to add another carousel ad variation to an existing carousel campaign

add_linkedin_creative ✏️ **USE THIS TOOL WHEN:** User wants to add another IMAGE ad/creative to an EXISTING LinkedIn image campaign

add_linkedin_text_creative ✏️ **USE THIS TOOL WHEN:** User wants to add another text ad to an EXISTING TEXT_AD campaign

add_linkedin_video_creative ✏️ **USE THIS TOOL WHEN:** User wants to add another video ad to an EXISTING LinkedIn video campaign

analyze_linkedin_creative_performance 📖 User asks about ad/creative performance, wants to identify winning/losing ad variations, or asks about creative fatigue

analyze_linkedin_wasted_spend 📖 User asks about wasted ad spend, unprofitable campaigns, where their LinkedIn budget is being wasted, or wants to identify underperformers

associate_linkedin_conversion ✏️ User wants to add conversion tracking to a campaign

batch_update_linkedin_campaigns ✏️ User wants to update multiple LinkedIn campaigns at once (bulk operations)

clone_linkedin_campaign ✏️ User wants to duplicate, copy, or clone a LinkedIn campaign

create_linkedin_carousel_campaign ✏️ **USE THIS TOOL WHEN:** User wants to create a LinkedIn CAROUSEL ad campaign (2-10 swipeable image cards)

create_linkedin_image_campaign ✏️ ⚠️ STOP - DO NOT CALL THIS TOOL DIRECTLY! This tool creates REAL LinkedIn campaigns that cost REAL money

create_linkedin_text_campaign ✏️ **USE THIS TOOL WHEN:** User wants to create a LinkedIn TEXT ad campaign (desktop right rail/top banner)

create_linkedin_video_campaign ✏️ **USE THIS TOOL WHEN:** User wants to create a LinkedIn VIDEO ad campaign

delete_linkedin_creative ✏️ User wants to delete, archive, or remove a LinkedIn ad/creative

discover_linkedin_assets 📖 User wants to find existing images/videos in their LinkedIn account to reuse

explain_linkedin_anomaly 📖 User asks why their LinkedIn metrics changed, wants to understand a performance drop/spike, or says something like "My LinkedIn leads dropped 40%, why?" Explai

explain_linkedin_objectives 📖 User asks about LinkedIn campaign objectives or which one to choose

generate_linkedin_ad_creatives 📖 User needs ad copy for LinkedIn campaigns

get_linkedin_audience_insights 📖 User asks about B2B audience demographics, which professional segments perform best, targeting optimization, or wants to understand their LinkedIn audience brea

get_linkedin_campaign_performance 📖 User asks about LinkedIn Ads performance, campaign metrics, B2B engagement, ROAS, or wants to understand how their LinkedIn campaigns are performing

get_linkedin_campaign_structure 📖 User wants full details about a specific LinkedIn campaign

get_linkedin_campaign_targeting 📖 User wants to copy targeting from one campaign to another

get_linkedin_engagement_metrics 📖 User asks specifically about LinkedIn engagement, social actions, lead generation metrics, or video performance

get_linkedin_organizations 📖 Fetch the LinkedIn Organizations (Company Pages) AND Ad Accounts the user can manage

list_linkedin_campaign_groups 📖 User wants to see their LinkedIn campaign groups (also called campaign folders or groups)

list_linkedin_campaigns 📖 User wants to see all their LinkedIn campaigns with performance metrics

list_linkedin_conversions 📖 User wants to see available conversion tracking options

list_linkedin_creatives 📖 User wants to see all ads in a LinkedIn campaign

manage_linkedin_conversions ✏️ User wants to manage LinkedIn conversion tracking - list, create, associate conversions, or set up full conversion tracking

optimize_linkedin_budget 📖 User asks how to allocate their LinkedIn budget, wants budget optimization recommendations, or asks "How should I split my LinkedIn spend?" Uses linear program

pause_linkedin_campaign ✏️ User wants to pause an active LinkedIn campaign

pause_linkedin_creative ✏️ User wants to pause a specific ad within a campaign

research_business_for_linkedin_targeting 📖 User wants targeting recommendations based on their business

resume_linkedin_campaign ✏️ User wants to resume a paused LinkedIn campaign

resume_linkedin_creative ✏️ User wants to resume a paused ad

search_linkedin_targeting 📖 User needs to find targeting URNs for LinkedIn campaigns

select_linkedin_campaign_type 📖 User wants to create a LinkedIn ad campaign but hasn't specified the campaign type (image, video, carousel, or text)

update_linkedin_campaign ✏️ User wants to modify LinkedIn campaign settings

update_linkedin_campaign_budget ✏️ User wants to change a LinkedIn campaign's budget (daily or total)

update_linkedin_campaign_group ✏️ User wants to modify a LinkedIn campaign group (rename, change status, update budget)

update_linkedin_campaign_schedule ✏️ User wants to change a LinkedIn campaign's end date or schedule

update_linkedin_campaign_targeting ✏️ User wants to add or remove targeting criteria from a LinkedIn campaign

update_linkedin_creative ✏️ User wants to edit a LinkedIn ad/creative

validate_and_prepare_linkedin_assets ✏️ User provides image URLs to validate BEFORE creating LinkedIn image campaign

Meta Ads (36 tools)

add_meta_ad ✏️ User wants to add another ad/creative variation to an EXISTING ad set

add_meta_ad_set ✏️ User wants to add a new ad set to an EXISTING campaign

analyze_meta_ad_performance 📖 User wants detailed analysis of specific Meta ads, creative performance, or wants to identify winning/losing ad variations

analyze_meta_audiences 📖 User asks about Meta/Facebook/Instagram audience performance by demographics, age group or gender targeting optimization, audience saturation, or which demograp

analyze_meta_wasted_spend 📖 User asks about Meta/Facebook/Instagram ad spend efficiency, wasted money, underperforming campaigns, placement optimization, or creative fatigue

browse_meta_targeting 📖 User wants to browse all targeting options in a specific category without a search query

create_meta_carousel_campaign ✏️ User wants to create a Meta (Facebook/Instagram) carousel ad campaign with multiple images

create_meta_dco_ad ✏️ User wants Meta to automatically TEST MULTIPLE IMAGES and find the best combination

create_meta_image_campaign ✏️ User wants to create a Meta (Facebook/Instagram) single-image ad campaign

create_meta_video_campaign ✏️ User wants to create a Meta (Facebook/Instagram) video ad campaign

detect_meta_creative_fatigue 📖 User asks about creative fatigue, ad refresh timing, frequency management, declining CTR, when to replace ads, or audience exhaustion on Meta/Facebook/Instagram

discover_meta_assets 📖 User wants to browse existing images in their Meta Ad Library for reuse in new campaigns

duplicate_meta_campaign ✏️ User wants to duplicate/copy an existing Meta campaign with all its ad sets, ads, and settings

explain_meta_anomaly 📖 User asks why Meta/Facebook/Instagram performance dropped or changed, what happened to their ROAS/CTR/CPM, or wants to understand why a metric changed during a

get_meta_ad_creatives 📖 User wants to see their Meta ad creatives, ad copy, media URLs, or creative performance

get_meta_audience_insights 📖 User asks about audience demographics, which placements perform best, device breakdown, or targeting optimization for Meta ads

get_meta_campaign_details 📖 User wants to see detailed information about a specific Meta campaign, including its full structure (ad sets, ads, targeting, budgets)

get_meta_campaign_performance 📖 User asks about Meta/Facebook/Instagram ad performance, campaign metrics, ROAS, spend analysis, or wants to understand how their Meta ads are performing

get_meta_lead_form_submissions 📖 User wants to see lead submissions, lead data, or leads collected from a Meta lead form

list_meta_ad_sets 📖 User wants to see the ad sets within a specific Meta campaign, including their targeting, budgets, and optimization settings

list_meta_ads 📖 User wants to see the individual ads within a specific Meta ad set, including their status and creative information

list_meta_campaigns 📖 User wants to see their existing Meta/Facebook/Instagram campaigns, browse campaign structure, or find a campaign ID

list_meta_custom_audiences 📖 User wants to browse, list, or select Custom Audiences for targeting — DB lists, lookalike audiences, remarketing segments, website visitors, engagement audienc

list_meta_instagram_accounts 📖 User wants to run ads on Instagram, asks about Instagram accounts, or you need to find the instagram_account_id before campaign creation

list_meta_lead_forms 📖 User wants to see their Meta lead generation forms, list lead forms, or find a lead form ID

list_meta_pixels 📖 User wants conversion tracking, asks about Meta Pixels, or before creating OUTCOME_SALES campaigns

optimize_meta_budget 📖 User asks about Meta/Facebook/Instagram budget optimization, reallocating ad spend, maximizing conversions with their budget, or wants data-driven budget recomm

optimize_meta_placements 📖 User asks about Meta/Facebook/Instagram placement performance, which placements work best, Feed vs Stories vs Reels, should they use Audience Network, or wants

pause_meta_campaign ✏️ User wants to pause a running Meta campaign

resume_meta_campaign ✏️ User wants to resume a paused Meta campaign

search_meta_targeting 📖 User wants to find targeting options for their Meta (Facebook/Instagram) ad campaigns

select_meta_campaign_type 📖 User wants to create a Meta (Facebook/Instagram) ad campaign but hasn't specified the campaign type (image, video, or carousel)

update_meta_ad ✏️ User wants to update an individual Meta ad — pause/resume it, rename it, or swap its creative

update_meta_ad_set ✏️ User wants to edit an existing Meta ad set's targeting, budget, bid, placements, schedule, or optimization settings

update_meta_campaign ✏️ User wants to update an existing Meta campaign's status, budget, name, or schedule

validate_and_prepare_meta_assets ✏️ User wants to upload NEW images for Meta campaigns

Monitoring & Reporting (13 tools)

create_monitor ✏️ Create a monitoring alert for your campaigns

delete_monitor ✏️ Delete a monitoring alert by its task ID

generate_report_now ✏️ Generate an immediate performance report and deliver it now

get_monitor_history 📖 Show trigger history for a monitoring alert

get_research_status 📖 Check the status of a research job

list_monitors 📖 List all your monitoring alerts

list_pending_actions 📖 List auto-actions waiting for your approval

list_scheduled_tasks 📖 List all your scheduled automation tasks

manage_action ✏️ Approve or reject a pending auto-action

manage_scheduled_task ✏️ Manage a scheduled task — pause, resume, or delete

schedule_brief ✏️ Schedule recurring performance briefs delivered to your inbox

start_research ✏️ Start an AI-powered research job (runs in background)

test_monitor 📖 Dry-run a monitor against current data WITHOUT triggering alerts or sending notifications

TikTok Ads (29 tools)

add_tiktok_ad ✏️ Add a new ad to an existing TikTok ad group

add_tiktok_ad_group ✏️ Add a new ad group to an existing TikTok campaign

analyze_tiktok_geo_performance 📖 Analyze TikTok geographic/country-level performance

analyze_tiktok_wasted_spend 📖 Analyze TikTok campaigns for wasted ad spend

create_tiktok_campaign ✏️ User wants to create a TikTok ad campaign with IMAGES, Spark Ads, or Carousel ads (not video)

create_tiktok_carousel_card ✏️ Create a carousel card from multiple images for TikTok carousel ads

create_tiktok_video_campaign ✏️ User wants to create a TikTok ad campaign with a VIDEO (not images)

detect_tiktok_creative_fatigue 📖 Detect TikTok creative fatigue using video-specific metrics (hook rate decline, completion rate decline, engagement decline, frequency)

discover_tiktok_assets 📖 User wants to reuse existing TikTok images instead of uploading new ones

explain_tiktok_anomaly 📖 Explain why a TikTok metric changed during a specific period

get_tiktok_ad_performance 📖 Get TikTok ad-level performance with creative details, video metrics, and engagement

get_tiktok_audience_insights 📖 Analyze TikTok audience segment performance by age, gender, and combined demographics

get_tiktok_campaign_details 📖 Get detailed information about a specific TikTok campaign including status, budget, objective, and timestamps

get_tiktok_campaign_performance 📖 Get TikTok campaign performance metrics including TikTok-specific video and engagement data

list_tiktok_ad_groups 📖 List TikTok ad groups

list_tiktok_ads 📖 List TikTok ads

list_tiktok_campaigns 📖 List all TikTok campaigns with their status, objective, and budget

optimize_tiktok_budget 📖 Optimize TikTok budget allocation using linear programming to maximize conversions

pause_tiktok_ad ✏️ Pause a TikTok ad

pause_tiktok_ad_group ✏️ Pause a TikTok ad group

pause_tiktok_campaign ✏️ Pause a TikTok campaign

resume_tiktok_ad ✏️ Resume a paused TikTok ad

resume_tiktok_ad_group ✏️ Resume a paused TikTok ad group

resume_tiktok_campaign ✏️ Resume a paused TikTok campaign

search_tiktok_targeting 📖 Search TikTok targeting options for campaign creation and ad group management

update_tiktok_ad_group ✏️ Update TikTok ad group settings: name, budget, targeting (age, gender, locations), schedule

update_tiktok_campaign ✏️ Update TikTok campaign settings like name, budget, or budget mode

upload_tiktok_images ✏️ Upload images to TikTok Asset Library from public URLs

validate_and_prepare_tiktok_assets ✏️ User provides image URLs to validate BEFORE creating TikTok image campaign

Adspirer REST API — adspirer.ai