Suggest Ad Content

Generate AI-suggested headlines and descriptions based on campaign keywords.

Analyzes campaign keywords and generates optimized ad content following creative guidelines:

15 headlines across 3 categories (What It Is, Benefits, Pain/Proof/CTA)
4 descriptions with value props and CTAs
All validated for character limits

Parameters:

campaign_id: The campaign to analyze (REQUIRED)
business_description: Optional context about the business
key_benefits: Optional list of benefits (e.g., [“fast setup”, “no dashboard”])
proof_points: Optional proof points (e.g., [{"number": "2000+", "metric": "campaigns"}])
pain_points: Optional pain points (e.g., [“manual ads”, “complex UI”])
customer_id: Optional

Returns:

suggested_headlines: 15 headlines ready to use
suggested_descriptions: 4 descriptions ready to use
headline_categories: Headlines organized by category
keyword_themes: Top themes from campaign keywords

Use this when:

User wants fresh ad copy ideas
User asks “what should my headlines be?”
Starting a new A/B test
Refreshing stale ad content

Execution time: 3-5 seconds

Example: User: “Suggest some better headlines for my campaign” Agent:

Uses suggest_ad_content to generate ideas
Shows suggestions organized by category
User picks favorites
Uses update_ad_headlines to apply selected headlines

POST

api

tools

suggest_ad_content

execute

Suggest Ad Content

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/suggest_ad_content/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "business_description": "string",
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "key_benefits": [
      "string"
    ],
    "pain_points": [
      "string"
    ],
    "proof_points": [
      "5-star rated on Trustpilot (4,200 reviews)",
      "Free shipping over $50"
    ]
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for suggest_ad_content)"
  },
  "success": true,
  "tool": "suggest_ad_content"
}

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for AI-powered ad content suggestions

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Update Ad ContentCombined update for ad content (headlines, descriptions, and/or final URLs). Use this for efficiency when updating multiple ad elements at once. Single API call with combined field mask. **Parameters:** - ad_id: The ad ID to update (REQUIRED) - ad_group_id: The ad group ID (REQUIRED) - headlines: Optional list of 3-15 headlines (max 30 chars each) - descriptions: Optional list of 2-4 descriptions (max 90 chars each) - final_urls: Optional list of landing page URLs - customer_id: Optional At least one of headlines, descriptions, or final_urls is required. **Execution time:** 2-4 seconds **Example:** User: "Update both headlines and descriptions for my ad" Agent: Uses update_ad_content with both headlines and descriptions in one call

Suggest Ad Content

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/suggest_ad_content/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "business_description": "string",
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "key_benefits": [
      "string"
    ],
    "pain_points": [
      "string"
    ],
    "proof_points": [
      "5-star rated on Trustpilot (4,200 reviews)",
      "Free shipping over $50"
    ]
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for suggest_ad_content)"
  },
  "success": true,
  "tool": "suggest_ad_content"
}