AdBrief API Documentation

Programmatic access to AdBrief's AI-powered ad strategy engine. Available on the Agency plan.

Authentication

All API requests require a Bearer token. Generate an API key from your Subscription page.

Authorization: Bearer adb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys start with adb_live_ for production and adb_test_ for sandbox. Include the header in every request. Keys can be revoked at any time from your dashboard.

Rate Limits

Agency plan includes 1,000 API calls per month. Rate limiting is applied per API key.

Header	Description
X-RateLimit-Limit	Monthly call limit (1000)
X-RateLimit-Remaining	Remaining calls this month
X-RateLimit-Reset	Unix timestamp when the limit resets

When you exceed the limit, the API returns 429 Too Many Requests. Contact support to increase your quota.

Endpoints

All endpoints accept JSON and return JSON. The base URL is https://adbrief.io.

Common Request Body

Most generation endpoints share these fields. Endpoint-specific fields are documented below.

Field	Type	Required	Description
platform	string	Yes	"meta" \| "google" \| "tiktok" \| "linkedin" \| "pinterest"
industry	string	Yes	One of 15 supported verticals (e.g. beauty_cosmetics, saas, ecommerce)
product	string	Yes	Product or service name/description
objective	string	Yes	"sales" \| "leads" \| "awareness" \| "traffic" \| "conversions"
budget	number	Yes	Monthly budget in EUR
audience	string	Yes	Target audience description
language	string	No	"fr" (default) or "en"

POST/api/v1/generate/strategy

Generate a complete 90-day campaign strategy with funnel stages, budget allocation, and KPIs.

Request

curl -X POST https://adbrief.io/api/v1/generate/strategy \
  -H "Authorization: Bearer adb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "meta",
  "industry": "beauty_cosmetics",
  "product": "Organic skincare serum",
  "objective": "sales",
  "budget": 3000,
  "audience": "F 25-45 France",
  "language": "fr"
}'

Response

{
  "id": "gen_abc123",
  "type": "strategy",
  "status": "completed",
  "data": {
    "summary": "90-day strategy for organic skincare...",
    "phases": [
      {
        "name": "Awareness",
        "duration": "Days 1-30",
        "budget_pct": 40,
        "objectives": ["Build audience", "Test creatives"],
        "kpis": { "cpm": 8.50, "reach": 150000 }
      }
    ],
    "total_budget": 3000,
    "currency": "EUR"
  },
  "usage": { "credits_used": 1 }
}

POST/api/v1/generate/ad-copy

Generate 15 ad copy variants organized by psychological angle (urgency, social proof, FOMO, etc.).

Request

curl -X POST https://adbrief.io/api/v1/generate/ad-copy \
  -H "Authorization: Bearer adb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "meta",
  "industry": "beauty_cosmetics",
  "product": "Organic skincare serum",
  "objective": "sales",
  "budget": 3000,
  "audience": "F 25-45 France",
  "language": "fr"
}'

Response

{
  "id": "gen_def456",
  "type": "ad_copy",
  "status": "completed",
  "data": {
    "variants": [
      {
        "angle": "social_proof",
        "headline": "Rejoint par 12 000+ femmes en France",
        "primary_text": "Notre serum bio a transforme...",
        "cta": "Decouvrir maintenant"
      }
    ],
    "count": 15,
    "platform_format": "meta_single_image"
  },
  "usage": { "credits_used": 1 }
}

POST/api/v1/generate/compliance

Check ad copy and landing page against EU advertising regulations (DSA, GDPR, ARPP, DGCCRF).

Request

curl -X POST https://adbrief.io/api/v1/generate/compliance \
  -H "Authorization: Bearer adb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "meta",
  "industry": "beauty_cosmetics",
  "ad_copy": "Guaranteed results in 7 days!",
  "landing_url": "https://example.com/serum",
  "language": "fr"
}'

Response

{
  "id": "gen_ghi789",
  "type": "compliance",
  "status": "completed",
  "data": {
    "score": 45,
    "verdict": "fail",
    "violations": [
      {
        "severity": "high",
        "rule": "ARPP_MISLEADING_CLAIMS",
        "text": "Guaranteed results in 7 days!",
        "reason": "Unsubstantiated efficacy claim",
        "fix": "Replace with 'Visible improvement reported by 80% of users after 4 weeks (clinical study, n=120)'"
      }
    ],
    "regulations_checked": ["DSA", "GDPR", "ARPP", "DGCCRF"]
  },
  "usage": { "credits_used": 1 }
}

POST/api/v1/generate/audit

Audit campaign metrics against industry benchmarks and return a prioritized action plan.

Request

curl -X POST https://adbrief.io/api/v1/generate/audit \
  -H "Authorization: Bearer adb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "meta",
  "industry": "beauty_cosmetics",
  "metrics": {
    "spend": 1500,
    "impressions": 180000,
    "clicks": 2700,
    "conversions": 45,
    "ctr": 1.5,
    "cpc": 0.56,
    "cpa": 33.33,
    "roas": 2.1
  },
  "language": "fr"
}'

Response

{
  "id": "gen_jkl012",
  "type": "audit",
  "status": "completed",
  "data": {
    "overall_score": 72,
    "verdict": "Above average",
    "metrics_analysis": [
      {
        "metric": "CTR",
        "value": 1.5,
        "benchmark": 1.2,
        "status": "good",
        "insight": "CTR is 25% above industry average"
      }
    ],
    "action_plan": [
      {
        "priority": 1,
        "action": "Test lookalike audiences to reduce CPA",
        "expected_impact": "15-20% CPA reduction"
      }
    ]
  },
  "usage": { "credits_used": 1 }
}

POST/api/v1/generate/report

Generate a client-ready weekly or monthly performance report with charts data and recommendations.

Request

curl -X POST https://adbrief.io/api/v1/generate/report \
  -H "Authorization: Bearer adb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "meta",
  "industry": "beauty_cosmetics",
  "client_name": "Belle Naturelle",
  "period": "last_7_days",
  "metrics": {
    "spend": 500,
    "impressions": 62000,
    "clicks": 930,
    "conversions": 18,
    "roas": 3.2
  },
  "language": "fr"
}'

Response

{
  "id": "gen_mno345",
  "type": "report",
  "status": "completed",
  "data": {
    "title": "Rapport Hebdomadaire - Belle Naturelle",
    "period": "7-13 April 2026",
    "executive_summary": "Strong week with ROAS above target...",
    "sections": [
      {
        "name": "Performance Overview",
        "metrics": { "spend": 500, "roas": 3.2 }
      }
    ],
    "recommendations": [
      "Increase budget by 20% on top-performing ad set",
      "Refresh creative for ad set 2 showing fatigue signals"
    ]
  },
  "usage": { "credits_used": 1 }
}

Errors

The API uses standard HTTP status codes. All error responses include a JSON body with error and message fields.

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Monthly API call limit reached. Resets on May 1, 2026.",
  "status": 429
}

Status	Error Code	Description
400	INVALID_REQUEST	Missing or invalid request body fields
401	UNAUTHORIZED	Missing or invalid API key
403	PLAN_REQUIRED	API access requires the Agency plan
404	NOT_FOUND	Endpoint does not exist
422	VALIDATION_ERROR	Request body failed validation (e.g. unknown platform)
429	RATE_LIMIT_EXCEEDED	Monthly API call limit reached
500	INTERNAL_ERROR	Unexpected server error -- retry or contact support