# Admanage API (llms.txt)

> v1 API for managing ad accounts, launching ads, querying reports, browsing media, duplicating campaigns/ad sets/ads, and automating workflows.

Base URL: https://api.admanage.ai
Versioned base: https://api.admanage.ai/v1
Full docs UI: https://admanage.ai/api-docs

## Authentication

Every request (except GET /v1/health and GET /llms.txt) MUST include an Authorization header with a Bearer token.

**Header format:**
```
Authorization: Bearer YOUR_API_KEY
```

**Important:** Do NOT use x-api-key or any other header name. The ONLY accepted format is the Authorization header with a Bearer prefix.

**Example:**
```bash
curl -sS "https://api.admanage.ai/v1/adaccounts" \
  -H "Authorization: Bearer ak_N-XqphL3DxvA..."
```

**Common mistakes:**
- Using x-api-key: ak_... instead of Authorization: Bearer ak_... (will return 401)
- Forgetting the "Bearer " prefix (will return 401)
- Using query param ?api_key=... (not supported)

API keys are company-scoped — all data returned is automatically filtered to the company associated with the key.

If authentication fails, the API returns:
```json
{ "success": false, "error": { "code": "unauthorized", "message": "Authorization header with Bearer token is required." } }
```

## Error Shape
```json
{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "human readable message",
    "requestId": "req-123"
  }
}
```

## Quick Launch (Fastest Path)
To launch an ad in 3 API calls:

1. **GET /v1/launch-defaults** — returns your saved page, insta, copy, CTA, link, UTM tags
2. **GET /v1/adsets?accountId=act_123** — returns ad sets with value/label ready for launch
3. **POST /v1/launch** — launch with defaults + ad sets + media URL

Then poll **GET /v1/batch-status/:id** until complete.

Example (uses defaults — only need media + ad sets):
```bash
# Step 1: Get defaults
curl -sS "https://api.admanage.ai/v1/launch-defaults" -H "Authorization: Bearer <api_key>"

# Step 2: Get ad sets
curl -sS "https://api.admanage.ai/v1/adsets?accountId=act_384730851257635&limit=10" -H "Authorization: Bearer <api_key>"

# Step 3: Launch (fill in defaults from step 1, ad sets from step 2)
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [{
      "adAccountId": "act_384730851257635",
      "title": "Stop wasting time on ad management",
      "description": "Launch ads 10x faster with AdManage",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "adSets": [{ "value": "120248289622780456", "label": "US Broad 25-44" }],
      "media": [{ "url": "https://media.admanage.ai/acme/creative.mp4" }]
    }]
  }'

# Step 4: Poll until done
curl -sS "https://api.admanage.ai/v1/batch-status/9912" -H "Authorization: Bearer <api_key>"
```

## Health
- GET /v1/health
Sample:
```bash
curl -sS https://api.admanage.ai/v1/health
```
Response:
```json
{ "success": true, "status": "ok", "db": "ok" }
```

## Launch
Creates an ad batch and dispatches to the launcher service. Returns immediately with batch ID for async polling.
Supported platforms: facebook (Meta), tiktok, snapchat, pinterest, axon.

- POST /v1/launch
  Body: { ads: [...] }

Each ad is fully self-contained with its own platform, account, ad sets, and media.

### ads[] fields
| Field | Required | Description |
|-------|----------|-------------|
| adName | no | Custom ad name |
| adAccountId | yes | Ad account ID (e.g. "act_123" for Meta, "7486153503963054097" for TikTok) |
| workspaceId | no | Workspace ID for token lookup |
| platform | no | "facebook", "tiktok", "snapchat", "pinterest", "axon". Auto-detected from adAccountId (act_* = facebook, UUID = snapchat) or adSets if omitted |
| title | no | Headline / primary text |
| description | no | Body text |
| adDescription | no | Additional description |
| cta | no | Call-to-action: "LEARN_MORE", "SHOP_NOW", "SIGN_UP", etc. |
| link | no | Landing page URL |
| displaylink | no | Display link shown on ad |
| urlTags | no | UTM parameters appended to link |
| page | Meta only | Facebook Page ID to post from |
| insta | Meta only | Instagram account ID |
| adSets | yes | Array of ad sets to launch into (from GET /v1/adsets) |
| media | yes | Array of media objects (videos or images) |
| type | no | "single", "multi", "carousel", "flexible" (default "single") |
| selectedTikTokUserAccount | TikTok only | TikTok identity for ad attribution |
| axonEndCards | Axon only | End card configuration |

### adSets[] shape
These come from GET /v1/adsets. Pass the objects returned by that endpoint.

Minimum required fields:
```json
{ "value": "120248289622780456", "label": "US Broad 25-44" }
```

### media[] shape
Just provide the public URL — type and name are auto-derived from the filename extension:
```json
{ "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4" }
```
You can optionally include any of these fields:
```json
{
  "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4",
  "name": "creative-1.mp4",
  "type": "video",
  "thumbnail": "https://media.admanage.ai/admanage.ai/thumb-ERER_DE_red123D4kWzVhn.jpg"
}
```
Auto-detection: .mp4/.mov/.avi/.webm = video, .png/.jpg/.gif/.webp = image.
Note: `videos` is accepted as an alias for `media`.

### Example: Meta (Facebook/Instagram) Launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [
      {
        "adName": "Spring Sale - UGC",
        "adAccountId": "act_384730851257635",
        "workspaceId": "workspace_abc",
        "title": "Stop wasting time on ad management",
        "description": "Launch ads 10x faster with AdManage",
        "cta": "LEARN_MORE",
        "link": "https://admanage.ai/",
        "displaylink": "admanage.ai",
        "urlTags": "utm_source=facebook&utm_medium=paid",
        "page": "470703006115773",
        "insta": "17841471826052348",
        "adSets": [
          { "value": "120248289622780456", "label": "US Broad 25-44" }
        ],
        "media": [
          { "url": "https://media.admanage.ai/acme/Spring-Sale-UGC.mp4" }
        ]
      },
      {
        "adName": "Spring Sale - Product Demo",
        "adAccountId": "act_384730851257635",
        "workspaceId": "workspace_abc",
        "title": "Stop wasting time on ad management",
        "description": "Launch ads 10x faster with AdManage",
        "cta": "LEARN_MORE",
        "link": "https://admanage.ai/",
        "page": "470703006115773",
        "insta": "17841471826052348",
        "adSets": [
          { "value": "120248289622780456", "label": "US Broad 25-44" }
        ],
        "media": [
          { "url": "https://media.admanage.ai/acme/Product-Demo.mp4" }
        ]
      }
    ]
  }'
```

### Example: TikTok Launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [
      {
        "adName": "TikTok - Creator Testimonial",
        "platform": "tiktok",
        "adAccountId": "7486153503963054097",
        "workspaceId": "workspace_abc",
        "title": "Check this out",
        "cta": "LEARN_MORE",
        "link": "https://admanage.ai/",
        "adSets": [
          { "value": "1857570827480306", "label": "Prospecting Ad Group" }
        ],
        "media": [
          { "url": "https://media.admanage.ai/acme/ugc-creator-testimonial.mp4" }
        ]
      }
    ]
  }'
```

### Example: Snapchat Launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [
      {
        "adName": "Snap - Creative 1",
        "adAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
        "workspaceId": "workspace_abc",
        "cta": "LEARN_MORE",
        "link": "https://admanage.ai/",
        "adSets": [
          { "value": "4dc89846-99ca-4bd2-8806-180d1f137f0a", "label": "Landing Page Views Ad Set" }
        ],
        "media": [
          { "url": "https://media.admanage.ai/acme/snap-creative.png" }
        ]
      }
    ]
  }'
```

### Example: Pinterest Launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [
      {
        "adName": "Pinterest - Spring Collection",
        "platform": "pinterest",
        "adAccountId": "549769890977",
        "workspaceId": "workspace_abc",
        "title": "Spring collection",
        "description": "Shop our new arrivals",
        "cta": "LEARN_MORE",
        "link": "https://admanage.ai/",
        "adSets": [
          { "value": "2680088752242", "label": "Awareness Ad Group" }
        ],
        "media": [
          { "url": "https://media.admanage.ai/acme/pin-creative.png" }
        ]
      }
    ]
  }'
```

### Example: Axon Launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [
      {
        "adName": "Axon - Creative 1",
        "platform": "axon",
        "adAccountId": "1159321785",
        "workspaceId": "workspace_abc",
        "link": "https://admanage.ai/",
        "cta": "LEARN_MORE",
        "axonEndCards": [
          { "id": "endcard-1", "name": "Default End Card" }
        ],
        "adSets": [],
        "media": [
          { "url": "https://media.admanage.ai/acme/axon-creative.mp4" }
        ]
      }
    ]
  }'
```

### Launch Response (all platforms, 202 Accepted)
```json
{
  "success": true,
  "message": "Ad launch initiated successfully",
  "adBatchSlug": "a1b2c3d4",
  "adBatchId": 9912,
  "isAsync": true
}
```
After launching, poll GET /v1/batch-status/{adBatchId} until status is "success" or "error".

### Legacy format
The old `creativeState` wrapper format is still fully supported:
```json
{ "creativeState": { "globalDefaults": { ... }, "rows": [ ... ] } }
```

### Re-launch an existing batch
- POST /v1/launch/from-draft
  Body: { batchId }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch/from-draft" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"batchId": 9911}'
```
Response (202):
```json
{
  "success": true,
  "message": "Ad launch initiated from draft",
  "adBatchSlug": "batch-abc123",
  "adBatchId": 9911,
  "isAsync": true
}
```

### Check Launch Batch Status
Poll this endpoint after launching to track progress.

- GET /v1/batch-status/:id
```bash
curl -sS "https://api.admanage.ai/v1/batch-status/9911" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "status": "processing",
  "progress": 62,
  "totalAds": 20,
  "successfulAds": 12,
  "failedAds": 1,
  "message": "Launching..."
}
```

## Accounts + Profiles
- GET /v1/adaccounts
  Query: page, limit
```bash
curl -sS "https://api.admanage.ai/v1/adaccounts?page=1&limit=25" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "data": [
    {
      "id": 101,
      "accountId": "act_123456789",
      "accountName": "Main Account",
      "businessId": "act_123456789",
      "businessName": "Acme Holdings",
      "workspaceId": "workspace_abc",
      "company": "acme",
      "type": "facebook",
      "updatedAt": "2026-02-18T08:25:12.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}
```

- GET /v1/profiles
  Returns Facebook Pages, Instagram accounts, and Threads profiles associated with your ad account.
  Use the `pageId` values as the `page` (Facebook) and `insta` (Instagram) fields when launching ads.

  Query parameters:
  | Param | Required | Description |
  |-------|----------|-------------|
  | businessId | no | Ad account ID (e.g. "act_123"). If omitted, returns all profiles for your company |
  | workspaceId | no | Workspace ID. Auto-discovered from ad account if omitted |
  | type | no | Filter by type: "facebook", "instagram", or "threads" |
  | refresh | no | Set to "true" to bypass DB cache and fetch live from Facebook Graph API |

```bash
# List all profiles (simplest — no params needed)
curl -sS "https://api.admanage.ai/v1/profiles" \
  -H "Authorization: Bearer <api_key>"

# Filter by ad account
curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123" \
  -H "Authorization: Bearer <api_key>"

# Filter by type
curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123&type=facebook" \
  -H "Authorization: Bearer <api_key>"

# Force refresh from Facebook Graph API
curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123&refresh=true" \
  -H "Authorization: Bearer <api_key>"
```
Use the `pageId` from facebook profiles as the `page` field in launch requests.
Use the `pageId` from instagram profiles as the `insta` field in launch requests.

```json
{
  "success": true,
  "data": {
    "profiles": [
      {
        "pageId": "470703006115773",
        "pageName": "Acme Brand Page",
        "type": "facebook",
        "pagePicture": "https://scontent.xx.fbcdn.net/...",
        "businessId": "act_123456789",
        "workspaceId": "workspace_abc"
      },
      {
        "pageId": "17841405999999999",
        "pageName": "acme.official",
        "type": "instagram",
        "pagePicture": "https://scontent.xx.fbcdn.net/...",
        "businessId": "act_123456789",
        "workspaceId": "workspace_abc",
        "relatedPageId": "470703006115773",
        "followers": 15200
      }
    ],
    "grouped": {
      "facebook": [ { "pageId": "470703006115773", "pageName": "Acme Brand Page", "..." : "..." } ],
      "instagram": [ { "pageId": "17841405999999999", "pageName": "acme.official", "..." : "..." } ],
      "threads": []
    },
    "counts": { "facebook": 1, "instagram": 1, "threads": 0 }
  }
}
```

- GET /v1/user/extended2
```bash
curl -sS https://api.admanage.ai/v1/user/extended2 \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "id": "usr_01HXYZABCDEF",
  "email": "user@acme.com",
  "name": "Acme Operator",
  "company": "acme",
  "organizations": [
    {
      "id": "org_123",
      "name": "Acme Holdings",
      "role": "admin"
    }
  ],
  "workspaces": [
    {
      "id": "workspace_abc",
      "name": "Main Workspace",
      "defaultAdAccountId": "act_123456789"
    }
  ],
  "settings": {
    "timezone": "America/Los_Angeles",
    "currency": "USD"
  }
}
```

- GET /v1/workspaces
  Query: page, limit
```bash
curl -sS "https://api.admanage.ai/v1/workspaces?page=1&limit=25" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "data": [
    {
      "id": "workspace_abc",
      "name": "Main Workspace",
      "company": "acme",
      "organizationId": "org_123",
      "metaAccountId": 12,
      "tiktokAccountId": null,
      "adAccounts": [
        {
          "accountId": "act_123456789",
          "accountName": "Main Account",
          "platform": "facebook"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}
```

## Templates
- GET /v1/templates/ad-copy
  Query: page, pageSize
```bash
curl -sS "https://api.admanage.ai/v1/templates/ad-copy?page=1&pageSize=10" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "data": [
    {
      "id": "copy_abcd1234",
      "name": "UGC Static Template",
      "defaultTitle": "Free Trial",
      "defaultDescription": "Try it today",
      "businessId": "act_123456789",
      "workspaceId": "workspace_abc",
      "updatedAt": "2026-02-18T08:25:12.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  }
}
```

- GET /v1/templates/ad-copy/:id
```bash
curl -sS "https://api.admanage.ai/v1/templates/ad-copy/copy_abc" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "id": "copy_abcd1234",
  "name": "UGC Static Template",
  "businessId": "act_123456789",
  "workspaceId": "workspace_abc",
  "templateData": {
    "globalDefaults": {
      "title": "Spring Launch",
      "description": "Top-performing variants",
      "cta": "SHOP_NOW"
    },
    "rows": [
      {
        "adName": "Creative 1",
        "headline": "New collection",
        "description": "Shop now",
        "videos": ["https://media.admanage.ai/example/ad-1.mp4"]
      }
    ]
  }
}
```

## Performance (Campaigns + Ad Sets)
Retrieve campaign and ad set structures from your ad accounts. Data is synced from ad platforms — use these to discover IDs for launching, duplicating, or querying reports.

### Typical workflow
1. GET /v1/adaccounts → find your accountId (e.g. "act_384730851257635") and workspaceId
2. GET /v1/profiles?businessId=act_384730851257635 → get Facebook Page IDs (`page`) and Instagram IDs (`insta`)
3. GET /v1/campaigns?accountId=act_384730851257635 → list campaigns, get campaignId
4. GET /v1/adsets?campaignId=120247699100220456 → list ad sets in that campaign, get adSetId
5. POST /v1/launch → launch with page, insta, adSets, and media
6. GET /v1/reports/query?accountIds=act_384730851257635&metrics=spend,impressions,clicks → ad-level performance data

### GET /v1/campaigns
List campaigns aggregated from ad sets. Campaigns are grouped from ad set records, so totalSpend and adSetCount reflect what's stored in AdManage.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| page | no | Page number (default 1) |
| limit | no | Results per page, max 100 (default 25) |
| accountId | no | Filter by ad account ID (also accepts adAccountId) |
| platform | no | Filter by platform: "facebook", "tiktok", "pinterest", "snapchat" |
| status | no | Filter by campaign status: "ACTIVE", "PAUSED", etc. |

```bash
curl -sS "https://api.admanage.ai/v1/campaigns?page=1&limit=25&accountId=act_384730851257635" \
  -H "Authorization: Bearer <api_key>"
```

Response fields:
| Field | Type | Description |
|-------|------|-------------|
| campaignId | string | Facebook/TikTok/Pinterest campaign ID |
| campaignName | string | Campaign name |
| platform | string | "facebook", "tiktok", "pinterest", "snapchat" |
| accountId | string | Ad account ID (e.g. "act_384730851257635") |
| status | string | Campaign status ("ACTIVE", "PAUSED", "DELETED", "ARCHIVED") |
| totalSpend | number | Sum of spend across all ad sets in this campaign |
| adSetCount | number | Number of ad sets in this campaign |
| lastUpdated | string | ISO datetime of most recent ad set update |

```json
{
  "data": [
    {
      "campaignId": "120247699100220456",
      "campaignName": "Q1 Prospecting - Broad",
      "platform": "facebook",
      "accountId": "act_384730851257635",
      "status": "ACTIVE",
      "totalSpend": 842.22,
      "adSetCount": 4,
      "lastUpdated": "2026-02-19T21:12:45.787Z"
    },
    {
      "campaignId": "120248100500330456",
      "campaignName": "Retargeting - Website Visitors",
      "platform": "facebook",
      "accountId": "act_384730851257635",
      "status": "ACTIVE",
      "totalSpend": 312.50,
      "adSetCount": 2,
      "lastUpdated": "2026-02-18T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 2,
    "totalPages": 1
  }
}
```

### GET /v1/adsets
List ad sets with status, spend, and ad count. Filter by campaign to drill into a specific campaign's ad sets.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| page | no | Page number (default 1) |
| limit | no | Results per page, max 100 (default 25) |
| campaignId | no | Filter by campaign ID |
| accountId | no | Filter by ad account ID (also accepts adAccountId) |
| platform | no | Filter by platform |
| status | no | Filter by ad set status |

```bash
curl -sS "https://api.admanage.ai/v1/adsets?campaignId=120247699100220456&limit=25" \
  -H "Authorization: Bearer <api_key>"
```

Response fields:
| Field | Type | Description |
|-------|------|-------------|
| id | number | Internal AdManage ad set ID |
| adSetId | string | Platform ad set ID (use this for duplication/delete) |
| name | string | Ad set name |
| value | string | Same as adSetId — launch-ready alias for ads[].adSets[].value |
| label | string | Same as name — launch-ready alias for ads[].adSets[].label |
| campaignId | string | Parent campaign ID |
| campaignName | string | Parent campaign name |
| account_id | string | Ad account ID (with act_ prefix for Meta) |
| platform | string | "facebook", "tiktok", "pinterest", "snapchat" |
| status | string | Ad set status ("ACTIVE", "PAUSED", etc.) |
| campaignStatus | string | Parent campaign status |
| adSpend | number | Total spend for this ad set |
| adCount | number | Number of ads in this ad set |
| lastUpdated | string | ISO datetime of last update |

**Tip:** Each ad set object includes `value` and `label` fields, so you can pass them directly into `ads[].adSets[]` when launching.

```json
{
  "data": [
    {
      "id": 4521,
      "adSetId": "120248289622780456",
      "name": "US Broad - Women 25-44",
      "value": "120248289622780456",
      "label": "US Broad - Women 25-44",
      "campaignId": "120247699100220456",
      "campaignName": "Q1 Prospecting - Broad",
      "account_id": "act_384730851257635",
      "platform": "facebook",
      "status": "ACTIVE",
      "campaignStatus": "ACTIVE",
      "adSpend": 214.11,
      "adCount": 8,
      "lastUpdated": "2026-02-19T21:12:45.787Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 2,
    "totalPages": 1
  }
}
```

## Batches
- GET /v1/adbatches
  Query: page, limit, search, status, user, adAccountId, workspaceId, privateHistory, dateFrom, dateTo
```bash
curl -sS "https://api.admanage.ai/v1/adbatches?page=1&limit=25&adAccountId=act_123" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "data": [
    {
      "id": 9911,
      "slug": "batch_2026_02_18_9911",
      "status": "processing",
      "user": "user@acme.com",
      "workspaceId": "workspace_abc",
      "adAccountId": "act_123456789",
      "createdAt": "2026-02-18T08:25:12.000Z",
      "updatedAt": "2026-02-18T08:28:41.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}
```

- GET /v1/adbatches/:id
```bash
curl -sS "https://api.admanage.ai/v1/adbatches/9911" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "id": 9911,
  "slug": "batch_2026_02_18_9911",
  "status": "processing",
  "workspaceId": "workspace_abc",
  "adAccountId": "act_123456789",
  "batchData": {
    "creativeState": {
      "globalDefaults": {
        "title": "Spring Launch",
        "description": "Top-performing variants",
        "cta": "SHOP_NOW"
      },
      "rows": [
        { "adName": "Creative 1", "headline": "New collection" }
      ]
    }
  }
}
```

- GET /v1/launch/batch/:batchId
```bash
curl -sS "https://api.admanage.ai/v1/launch/batch/9911" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "batch": {
    "id": 9911,
    "status": "processing",
    "progress": {
      "total": 20,
      "processed": 12,
      "successful": 11,
      "failed": 1,
      "percentage": 60
    },
    "alreadyProcessing": false
  }
}
```

## Reports (Ad Performance Data)
Query ad performance data across platforms. Uses BigQuery for Facebook, falls back to platform-specific APIs for TikTok and Pinterest.
Each row represents one ad (or grouped entity), with the metrics you requested.

### GET /v1/reports/query
The main reporting endpoint. Returns ad-level performance data with thumbnails.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| accountIds | yes | Comma-separated ad account IDs (e.g. "act_384730851257635" or "act_123,act_456") |
| startDate | yes | Start date (YYYY-MM-DD) |
| endDate | yes | End date (YYYY-MM-DD) |
| metrics | yes | Comma-separated metric names (see below) |
| groupBy | no | Dimension to group by (default: "adId"). Options: adId, adName, campaignName, adsetName, landingPage, assetType, creative, videoAsset, imageAsset, body, title, callToActionType, adStatus, objective |
| sortBy | no | Metric to sort by (e.g. "spend", "impressions") |
| sortDirection | no | "ASC" or "DESC" (default DESC) |
| limit | no | Max rows (default 25, max 100) |
| offset | no | Skip rows for pagination (default 0) |
| filters | no | JSON-encoded filters array (see filter operators below) |
| filterOperator | no | "AND" or "OR" — how multiple filters combine (default "AND") |
| excludePatterns | no | Comma-separated patterns to strip from ad names when grouping (e.g. "- Copy,- v2") |
| workspaceId | no | Workspace ID for token resolution (TikTok/Pinterest) |

Common metrics (performance):
- spend, impressions, clicks, reach, outboundClicks, linkClicks, landingPageViews, results

Common metrics (calculated):
- cpm, ctr, clicksCost (CPC), frequency, costPerResult, roas

Video metrics:
- videoViews (3s), thruPlays (15s), videoP025Watched, videoP050Watched, videoP075Watched, videoP100Watched
- hookRate (3s views / impressions), vtr (100% watched / impressions), holdPlay (thruPlays / 3s views)

Conversion metrics:
- purchases, purchaseValue, purchaseRoas, addToCart, registrations, leads, contentViews, appInstalls

Use GET /v1/reports/fields for the complete list with descriptions.

```bash
curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,clicks,ctr,cpm,reach,videoViews,hookRate,purchases,purchaseValue,roas,costPerResult&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=10" \
  -H "Authorization: Bearer <api_key>"
```

Response fields per row:
| Field | Type | Description |
|-------|------|-------------|
| adId | string | Ad ID (or grouped dimension value) |
| adName | string | Ad name (included automatically) |
| campaignName | string | Parent campaign name |
| adsetName | string | Parent ad set name |
| thumbnailUrl | string | Creative thumbnail URL |
| _accountId | string | Ad account ID this row belongs to |
| spend | number | Total amount spent |
| impressions | number | Total impressions |
| clicks | number | Total clicks |
| ctr | number | Click-through rate (clicks / impressions) |
| cpm | number | Cost per mille (spend / impressions * 1000) |
| (other metrics) | number | As requested in the metrics parameter |

```json
{
  "success": true,
  "data": [
    {
      "adId": "120247682651440456",
      "adName": "UGC Creator Testimonial - v2",
      "campaignName": "Q1 Prospecting - Broad",
      "adsetName": "US Broad - Women 25-44",
      "thumbnailUrl": "https://files.admanage.app/act_384730851257635/120247682651440456",
      "_accountId": "act_384730851257635",
      "spend": 192.06,
      "impressions": 46650,
      "clicks": 492,
      "ctr": 0.01054,
      "cpm": 4.117,
      "reach": 38200,
      "videoViews": 12800,
      "hookRate": 0.274,
      "purchases": 8,
      "purchaseValue": 640.00,
      "roas": 3.33,
      "costPerResult": 24.01
    },
    {
      "adId": "120247704303600456",
      "adName": "Product Demo - Spring Collection",
      "campaignName": "Q1 Prospecting - Broad",
      "adsetName": "US Broad - Men 25-54",
      "thumbnailUrl": "https://files.admanage.app/act_384730851257635/120247704303600456",
      "_accountId": "act_384730851257635",
      "spend": 50.50,
      "impressions": 22910,
      "clicks": 188,
      "ctr": 0.0082,
      "cpm": 2.204,
      "reach": 19400,
      "videoViews": 5600,
      "hookRate": 0.244,
      "purchases": 2,
      "purchaseValue": 180.00,
      "roas": 3.56,
      "costPerResult": 25.25
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 5,
    "hasMore": false
  },
  "metadata": {
    "platform": "facebook",
    "source": "bigquery"
  }
}
```

**Account validation:** The endpoint validates that the requested accountIds belong to your API key. If some accounts are invalid, valid ones are queried and a warning is returned for the skipped ones.

**Diagnostics (metadata.warnings):** When data is empty or partially unavailable, the response includes `metadata.warnings` — an array of human-readable strings explaining why. Examples:
- `"Reporting pipeline not configured for account act_123. Connect the account in AdManage settings to enable performance data."`
- `"No Facebook access token found. Ensure a token is connected in AdManage settings."`
- `"The following account IDs were skipped (not found for this API key): act_999"`
- `"No data found in reporting pipeline for the requested date range."`

```json
{
  "success": true,
  "data": [],
  "pagination": { "offset": 0, "limit": 25, "total": 0, "hasMore": false },
  "metadata": {
    "platform": "facebook",
    "source": "none",
    "warnings": [
      "Reporting pipeline not configured for account act_123. Connect the account in AdManage settings to enable performance data.",
      "No Facebook access token found. Ensure a token is connected in AdManage settings."
    ]
  }
}
```

**Filter operators:** EQUALS, NOT_EQUALS, HIGHER_THAN, LOWER_THAN, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, IN, NOT_IN, BETWEEN, NOT_BETWEEN, EMPTY, NOT_EMPTY

Example: Group by campaign name:
```bash
curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,clicks,purchases,roas&groupBy=campaignName&sortBy=spend&sortDirection=DESC&limit=25" \
  -H "Authorization: Bearer <api_key>"
```

Example: Group by ad set name:
```bash
curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,ctr,roas&groupBy=adsetName&sortBy=spend&sortDirection=DESC&limit=25" \
  -H "Authorization: Bearer <api_key>"
```

### GET /v1/reports/fields
Returns all available dimensions and metrics for building report queries. Each entry includes name, label, type, format, and description.

```bash
curl -sS "https://api.admanage.ai/v1/reports/fields" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "dimensions": [
    { "name": "adId", "label": "Unique Ad", "type": "dimension" },
    { "name": "adName", "label": "Ad name", "type": "dimension" },
    { "name": "adsetName", "label": "Adset name", "type": "dimension" },
    { "name": "campaignName", "label": "Campaign name", "type": "dimension" },
    { "name": "landingPage", "label": "Landing page", "type": "dimension" },
    { "name": "assetType", "label": "Ad type", "type": "dimension" },
    { "name": "creative", "label": "Creative", "type": "dimension" },
    { "name": "videoAsset", "label": "Video", "type": "dimension" },
    { "name": "imageAsset", "label": "Image", "type": "dimension" },
    { "name": "body", "label": "Copy", "type": "dimension" },
    { "name": "title", "label": "Headline", "type": "dimension" },
    { "name": "callToActionType", "label": "Call to action", "type": "dimension" },
    { "name": "adStatus", "label": "Ad status", "type": "dimension" },
    { "name": "objective", "label": "Campaign Objective", "type": "dimension" }
  ],
  "metrics": [
    { "name": "spend", "label": "Amount Spent", "type": "metric", "format": "MONEY" },
    { "name": "impressions", "label": "Impressions", "type": "metric", "format": "NUMBER" },
    { "name": "clicks", "label": "Clicks", "type": "metric", "format": "NUMBER" },
    { "name": "reach", "label": "Reach", "type": "metric", "format": "NUMBER" },
    { "name": "videoViews", "label": "3 second video views", "type": "metric", "format": "NUMBER" },
    { "name": "thruPlays", "label": "Thruplay", "type": "metric", "format": "NUMBER" },
    { "name": "purchases", "label": "Purchases", "type": "metric", "format": "NUMBER" },
    { "name": "purchaseValue", "label": "Purchase Value", "type": "metric", "format": "MONEY" },
    { "name": "leads", "label": "Leads", "type": "metric", "format": "NUMBER" },
    { "name": "results", "label": "Results", "type": "metric", "format": "NUMBER" },
    { "name": "cpm", "label": "CPM", "type": "calculated", "format": "MONEY" },
    { "name": "ctr", "label": "CTR", "type": "calculated", "format": "PERCENTAGE" },
    { "name": "clicksCost", "label": "CPC", "type": "calculated", "format": "MONEY" },
    { "name": "frequency", "label": "Frequency", "type": "calculated", "format": "FLOAT" },
    { "name": "hookRate", "label": "Hook Rate", "type": "calculated", "format": "PERCENTAGE" },
    { "name": "vtr", "label": "VTR", "type": "calculated", "format": "PERCENTAGE" },
    { "name": "roas", "label": "ROAS", "type": "calculated", "format": "FLOAT" },
    { "name": "purchaseCostPer", "label": "Cost Per Purchase", "type": "calculated", "format": "MONEY" },
    { "name": "costPerResult", "label": "Cost Per Result", "type": "calculated", "format": "MONEY" }
  ]
}
```

## Daily Ad Spend
Get daily ad spend per account across all connected platforms. Useful for balance management and budget monitoring.
Supports Facebook/Meta (via BigQuery + Graph API fallback), TikTok, Pinterest, and Snapchat.

### GET /v1/spend/daily
Returns daily spend broken down by ad account.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| startDate | yes | Start date (YYYY-MM-DD) |
| endDate | yes | End date (YYYY-MM-DD) |
| accountIds | no | Comma-separated ad account IDs to filter (defaults to all accounts) |
| workspaceId | no | Filter to a specific workspace |
| platform | no | Filter by platform: "facebook", "tiktok", "pinterest", "snapchat" |

Date range is capped at 90 days per request.

```bash
curl -sS "https://api.admanage.ai/v1/spend/daily?startDate=2026-03-01&endDate=2026-03-09" \
  -H "Authorization: Bearer <api_key>"
```

Example with filters:
```bash
curl -sS "https://api.admanage.ai/v1/spend/daily?startDate=2026-03-01&endDate=2026-03-09&accountIds=act_384730851257635&platform=facebook" \
  -H "Authorization: Bearer <api_key>"
```

Response:
```json
{
  "success": true,
  "data": [
    {
      "date": "2026-03-01",
      "accountId": "act_384730851257635",
      "accountName": "Admanage Limited",
      "platform": "facebook",
      "currency": "USD",
      "spend": 150.42
    },
    {
      "date": "2026-03-01",
      "accountId": "7486153503963054097",
      "accountName": "TikTok Main Account",
      "platform": "tiktok",
      "currency": "USD",
      "spend": 75.00
    },
    {
      "date": "2026-03-02",
      "accountId": "act_384730851257635",
      "accountName": "Admanage Limited",
      "platform": "facebook",
      "currency": "USD",
      "spend": 142.18
    }
  ],
  "metadata": {
    "startDate": "2026-03-01",
    "endDate": "2026-03-09",
    "accountCount": 2,
    "totalSpend": 367.60,
    "platforms": ["facebook", "tiktok"]
  }
}
```

If a platform fails (e.g. token expired), partial results are returned with an errors array:
```json
{
  "success": true,
  "data": [...],
  "metadata": {...},
  "errors": [
    { "platform": "tiktok", "message": "TikTok not connected" }
  ]
}
```

**Diagnostics (warnings):** When no accounts match, the response includes a top-level `warnings` array explaining why:
```json
{
  "success": true,
  "data": [],
  "metadata": { "startDate": "2026-03-01", "endDate": "2026-03-09", "accountCount": 0, "totalSpend": 0, "platforms": [] },
  "warnings": [
    "None of the requested account IDs (act_999) were found for this API key. Verify the account IDs are correct and connected in AdManage settings."
  ]
}
```

## Comments
Retrieve ad comments stored in AdManage. Comments are collected from Facebook/Meta via webhook subscriptions.

### GET /v1/comments
List comments with filtering and pagination.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| page | no | Page number (default 1) |
| limit | no | Results per page, max 100 (default 25) |
| accountId | no | Filter by ad account ID (also accepts adAccountId) |
| adId | no | Filter by specific ad ID |
| sentiment | no | Filter: "positive", "neutral", "negative" |
| hidden | no | Filter by hidden status: "true" or "false" |
| startDate | no | Start date (YYYY-MM-DD) |
| endDate | no | End date (YYYY-MM-DD) |
| search | no | Search in comment text, author, or ad name |
| sortBy | no | Sort field: "commentDate", "likes", "sentiment", "lastUpdated" (default: commentDate) |
| sortDirection | no | "ASC" or "DESC" (default: DESC) |

```bash
curl -sS "https://api.admanage.ai/v1/comments?page=1&limit=25&accountId=act_123" \
  -H "Authorization: Bearer <api_key>"
```

```json
{
  "success": true,
  "data": [
    {
      "id": 1234,
      "commentId": "123456789_987654321",
      "text": "Great product!",
      "author": "John Doe",
      "date": "2026-03-10T14:30:00.000Z",
      "likes": 5,
      "replyCount": 2,
      "sentiment": 5,
      "sentimentLabel": "positive",
      "hidden": false,
      "adId": "120248289622780456",
      "adName": "Spring Sale - UGC",
      "accountId": "act_123456789",
      "permalink": "https://www.facebook.com/...",
      "companyReply": "Thanks!",
      "companyReplyTime": "2026-03-10T15:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "totalPages": 6
  }
}
```

### GET /v1/comments/analytics
Get aggregated comment analytics: sentiment distribution, top ads by comments, and volume over time.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| accountId | no | Filter by ad account ID (also accepts adAccountId) |
| startDate | no | Start date (YYYY-MM-DD) |
| endDate | no | End date (YYYY-MM-DD) |

```bash
curl -sS "https://api.admanage.ai/v1/comments/analytics?accountId=act_123&startDate=2026-02-01&endDate=2026-03-01" \
  -H "Authorization: Bearer <api_key>"
```

```json
{
  "success": true,
  "data": {
    "summary": {
      "totalComments": 1250,
      "avgSentiment": 3.72,
      "analyzedComments": 1180,
      "hiddenComments": 15,
      "commentsWithReplies": 340
    },
    "sentimentDistribution": {
      "positive": { "count": 680, "percentage": 58 },
      "neutral": { "count": 350, "percentage": 30 },
      "negative": { "count": 150, "percentage": 13 }
    },
    "topAds": [
      {
        "adId": "120248289622780456",
        "adName": "Spring Sale - UGC",
        "commentCount": 85,
        "avgSentiment": 4.1,
        "totalLikes": 230
      }
    ],
    "volumeOverTime": [
      { "date": "2026-02-01T00:00:00.000Z", "count": 42 },
      { "date": "2026-02-02T00:00:00.000Z", "count": 38 }
    ]
  }
}
```

## Launch Drafts
Save, iterate, and launch ad drafts via the API.

- POST /v1/drafts
  Body: { title, businessId (required), workspaceId, status, state }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/drafts" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Draft","businessId":"act_123","state":{"globalDefaults":{"title":"Spring Sale"},"rows":[]}}'
```
Response (201):
```json
{
  "success": true,
  "data": {
    "id": 42,
    "title": "My Draft",
    "businessId": "act_123",
    "workspaceId": null,
    "status": "draft",
    "user": "user@acme.com",
    "company": "acme",
    "createdAt": "2026-02-19T10:00:00.000Z",
    "state": { "globalDefaults": { "title": "Spring Sale" }, "rows": [] }
  }
}
```

- GET /v1/drafts
  Query: page, limit, businessId, workspaceId, search
```bash
curl -sS "https://api.admanage.ai/v1/drafts?page=1&limit=25&businessId=act_123" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "data": [
    {
      "id": 42,
      "title": "My Draft",
      "businessId": "act_123",
      "workspaceId": null,
      "status": "draft",
      "user": "user@acme.com",
      "company": "acme",
      "createdAt": "2026-02-19T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 }
}
```

- GET /v1/drafts/:id
```bash
curl -sS "https://api.admanage.ai/v1/drafts/42" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "id": 42,
    "title": "My Draft",
    "businessId": "act_123",
    "status": "draft",
    "state": { "globalDefaults": { "title": "Spring Sale" }, "rows": [] },
    "createdAt": "2026-02-19T10:00:00.000Z"
  }
}
```

- PATCH /v1/drafts/:id
  Body: { title?, businessId?, workspaceId?, status?, state? }
```bash
curl -sS -X PATCH "https://api.admanage.ai/v1/drafts/42" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated Draft","state":{"globalDefaults":{"title":"Summer Sale"},"rows":[{"id":"row-1"}]}}'
```
```json
{
  "success": true,
  "data": {
    "id": 42,
    "title": "Updated Draft",
    "status": "draft",
    "state": { "globalDefaults": { "title": "Summer Sale" }, "rows": [{ "id": "row-1" }] }
  }
}
```

- DELETE /v1/drafts/:id
```bash
curl -sS -X DELETE "https://api.admanage.ai/v1/drafts/42" \
  -H "Authorization: Bearer <api_key>"
```
```json
{ "success": true, "message": "Draft deleted" }
```

- POST /v1/drafts/:id/launch
```bash
curl -sS -X POST "https://api.admanage.ai/v1/drafts/42/launch" \
  -H "Authorization: Bearer <api_key>"
```
Response (202):
```json
{
  "success": true,
  "message": "Ad launch initiated successfully",
  "adBatchSlug": "a1b2c3d4",
  "adBatchId": 9913,
  "isAsync": true
}
```

## Media Library
Browse, search, and filter creative assets in your media library.

- GET /v1/library/assets
  Query: search, filterType (all|image|video|gif), sortBy (dateCreated|dateModified|name|size), sortOrder (asc|desc), boardId, creativeStatus (raw|in_progress|approved|archived), launchStatus (Launched|Not Launched), launchChannels (comma-sep: meta,tiktok,snapchat,pinterest,axon), tags (comma-sep), dimension (1080x1920 or 9:16), uploader (email), limit (max 100), cursor
```bash
curl -sS "https://api.admanage.ai/v1/library/assets?limit=10&filterType=video&sortBy=dateCreated&sortOrder=desc" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "assets": [
    {
      "id": 12345,
      "adid": 67890,
      "name": "Spring-UGC.mp4",
      "url": "https://media.admanage.ai/acme/Spring-UGC.mp4",
      "thumbnail": "https://media.admanage.ai/acme/thumb-Spring-UGC.jpg",
      "mimeType": "video/mp4",
      "size": 15728640,
      "dimension": "1080x1920",
      "type": "video",
      "dateAdded": "2026-02-18T08:25:12.000Z",
      "lastUpdated": "2026-02-18T10:00:00.000Z",
      "uploaderStatus": "approved",
      "status": "Launched",
      "launchChannels": [
        { "platform": "meta", "adIds": ["120012345678901234"] }
      ],
      "tags": [{ "id": 1, "name": "UGC" }],
      "boardIds": [10, 22]
    }
  ],
  "nextCursor": "12344",
  "hasMore": true,
  "total": 847
}
```

- GET /v1/library/assets/:id
```bash
curl -sS "https://api.admanage.ai/v1/library/assets/12345" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "id": 12345,
    "name": "Spring-UGC.mp4",
    "url": "https://media.admanage.ai/acme/Spring-UGC.mp4",
    "type": "video",
    "transcript": "Hey guys, check out this amazing product...",
    "smartSummary": "UGC testimonial video featuring product demo",
    "smartTags": ["ugc", "testimonial", "product-demo"],
    "launchChannels": [
      { "platform": "meta", "adIds": ["120012345678901234"] }
    ]
  }
}
```

- GET /v1/library/boards
```bash
curl -sS "https://api.admanage.ai/v1/library/boards" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Q1 Creatives",
      "visibility": "team",
      "assetCount": 42,
      "children": [
        { "id": 11, "name": "UGC", "assetCount": 18, "children": [] }
      ]
    }
  ]
}
```

- GET /v1/library/boards/:id/assets
  Same query params and response shape as GET /v1/library/assets, scoped to a specific board.
```bash
curl -sS "https://api.admanage.ai/v1/library/boards/10/assets?limit=25" \
  -H "Authorization: Bearer <api_key>"
```

- GET /v1/library/tags
```bash
curl -sS "https://api.admanage.ai/v1/library/tags" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": [
    { "id": 1, "name": "UGC", "company": "acme" },
    { "id": 2, "name": "Product Demo", "company": "acme" }
  ]
}
```

## Manage (Create)
Create new campaigns and ad sets from scratch on Facebook.

- POST /v1/manage/create-campaign
  Create a new Facebook campaign.
  Body: { accountId, name, objective, status? ("ACTIVE"|"PAUSED", default "PAUSED"), buyingType? ("AUCTION"|"RESERVED"), specialAdCategories? (string[]), bidStrategy?, dailyBudget?, lifetimeBudget?, workspaceId? }

  Objectives: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_AWARENESS, OUTCOME_SALES, OUTCOME_APP_PROMOTION
  Bid strategies: LOWEST_COST_WITHOUT_CAP (default), LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS
  Special ad categories: EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS (pass [] if none)

```bash
curl -sS -X POST "https://api.admanage.ai/v1/manage/create-campaign" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"act_123","name":"Q2 Prospecting","objective":"OUTCOME_SALES","status":"PAUSED","dailyBudget":100}'
```
```json
{
  "success": true,
  "campaignId": "120248400000000001",
  "name": "Q2 Prospecting",
  "objective": "OUTCOME_SALES",
  "status": "PAUSED",
  "accountId": "act_123"
}
```

- POST /v1/manage/create-adset
  Create a new Facebook ad set inside an existing campaign.
  Body: { accountId, campaignId, name, status?, optimizationGoal?, billingEvent?, bidAmount?, dailyBudget?, lifetimeBudget?, startTime?, endTime?, targeting?, promotedObject?, destinationType?, workspaceId? }

  Optimization goals by objective:
  - OUTCOME_TRAFFIC → LANDING_PAGE_VIEWS (default), LINK_CLICKS, IMPRESSIONS, REACH
  - OUTCOME_LEADS → LEAD_GENERATION (default), QUALITY_LEAD
  - OUTCOME_SALES → OFFSITE_CONVERSIONS (default), VALUE
  - OUTCOME_AWARENESS → REACH (default), IMPRESSIONS, AD_RECALL_LIFT
  - OUTCOME_APP_PROMOTION → APP_INSTALLS (default), APP_EVENTS

  Destination types: WEBSITE (default), APP, MESSENGER, WHATSAPP, INSTAGRAM_DIRECT, ON_AD, WEBSITE_AND_PHONE_CALL
  Targeting: default is US broad. Example: { "geo_locations": { "countries": ["US","CA"] }, "age_min": 25, "age_max": 54 }

```bash
curl -sS -X POST "https://api.admanage.ai/v1/manage/create-adset" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"act_123","campaignId":"120248400000000001","name":"US Broad 25-54","optimizationGoal":"OFFSITE_CONVERSIONS","dailyBudget":50,"targeting":{"geo_locations":{"countries":["US"]},"age_min":25,"age_max":54},"promotedObject":{"pixel_id":"123456","custom_event_type":"PURCHASE"}}'
```
```json
{
  "success": true,
  "adSetId": "120248400000000002",
  "name": "US Broad 25-54",
  "campaignId": "120248400000000001",
  "status": "PAUSED",
  "accountId": "act_123"
}
```

## Manage (Duplicate)
Duplicate campaigns, ad sets, and ads on Facebook.

- POST /v1/manage/duplicate-adset
  Duplicate a Facebook ad set (1-10 copies). Uses smartCopy (sync first, async batch fallback for large ad sets).
  Body: { adSetId (or adsetId), accountId, copyCount (1-10), initialStatus ("ACTIVE"|"PAUSED"), targetCampaignId?, newName?, deepCopy? (default true), workspaceId? }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-adset" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"adsetId":"120248289622780456","accountId":"act_123","copyCount":2,"initialStatus":"PAUSED","deepCopy":true}'
```
```json
{
  "success": true,
  "originalAdSetId": "120248289622780456",
  "results": [
    { "copyNumber": 1, "success": true, "newAdSetId": "120248289622780457" },
    { "copyNumber": 2, "success": true, "newAdSetId": "120248289622780458" }
  ],
  "successCount": 2,
  "failCount": 0
}
```

- POST /v1/manage/duplicate-campaign
  Duplicate a Facebook campaign (1-10 copies). Same smartCopy pattern as ad set duplication.
  Body: { campaignId, accountId, copyCount (1-10), initialStatus ("ACTIVE"|"PAUSED"), newName?, deepCopy? (default true), workspaceId? }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-campaign" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"campaignId":"120247699100220456","accountId":"act_123","copyCount":1,"initialStatus":"PAUSED"}'
```
```json
{
  "success": true,
  "originalCampaignId": "120247699100220456",
  "results": [
    { "copyNumber": 1, "success": true, "newCampaignId": "120247699100220457" }
  ],
  "successCount": 1,
  "failCount": 0
}
```

- POST /v1/manage/duplicate-ad
  Duplicate a Facebook ad with optional creative modifications (primary text, headlines, URL, URL tags).
  Falls back to recreation (create new creative + ad) on pixel permission or lead form errors.
  Body: { adId, accountId, targetAdSetId, copyCount (1-10), initialStatus ("ACTIVE"|"PAUSED"), copyValues: { primaryText1-5?, headline1-5?, url?, urlTags?, adName? }, workspaceId? }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-ad" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"adId":"120012345678901234","accountId":"act_123","targetAdSetId":"120248289622780456","copyCount":1,"initialStatus":"PAUSED","copyValues":{"primaryText1":"New headline","adName":"My Ad Copy"}}'
```
```json
{
  "success": true,
  "originalAdId": "120012345678901234",
  "results": [
    { "copyNumber": 1, "success": true, "newAdId": "120012345678901235", "method": "copies" }
  ],
  "successCount": 1,
  "failCount": 0
}
```

Notes:
- deepCopy (default true): When true, copies all child objects (ads in ad sets, ad sets + ads in campaigns). Set to false to copy only the container.
- copyCount 1-10: Number of duplicates to create in one call.

## Automations

### List Rules
- GET /v1/automations
  Query: page, limit, status, workspaceId, search
```bash
curl -sS "https://api.admanage.ai/v1/automations?page=1&limit=25&status=active" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Pause low ROAS ads",
      "status": "active",
      "actionType": "pause_ad",
      "accountId": "act_123456789",
      "frequency": "daily",
      "scheduledDate": "2026-02-27",
      "scheduledTime": "09:00",
      "workspaceId": "workspace_abc",
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-25T14:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 }
}
```

### Get Rule
- GET /v1/automations/:id
  Returns the rule with its 10 most recent executions.
```bash
curl -sS "https://api.admanage.ai/v1/automations/1" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Pause low ROAS ads",
    "status": "active",
    "flow": { "nodes": [ { "id": "trigger-1", "type": "trigger", "data": {} }, { "id": "action-1", "type": "action", "data": {} } ] },
    "actionType": "pause_ad",
    "accountId": "act_123456789",
    "targetId": null,
    "newName": null,
    "frequency": "daily",
    "scheduledDate": "2026-02-27",
    "scheduledTime": "09:00",
    "dayOfWeek": null,
    "dayOfMonth": null,
    "startDate": null,
    "endDate": null,
    "userId": "usr_01HXYZ",
    "userEmail": "user@acme.com",
    "company": "acme",
    "workspaceId": "workspace_abc",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-25T14:30:00.000Z",
    "executions": [
      { "id": 101, "status": "completed", "executedAt": "2026-02-26T09:00:05.000Z", "completedAt": "2026-02-26T09:00:12.000Z", "duration": 7000, "errorMessage": null }
    ]
  }
}
```

### Create Rule
- POST /v1/automations
  Body: name (required), flow (required, object with nodes array), actionType (required), accountId (required), targetId?, newName?, frequency? ("one-time"|"daily"|"weekly"|"monthly", default "one-time"), scheduledDate?, scheduledTime?, dayOfWeek?, dayOfMonth?, startDate?, endDate?, status? (default "active"), workspaceId?
```bash
curl -sS -X POST "https://api.admanage.ai/v1/automations" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pause low ROAS ads","flow":{"nodes":[{"id":"trigger-1","type":"trigger","data":{}},{"id":"action-1","type":"action","data":{}}]},"actionType":"pause_ad","accountId":"act_123456789","frequency":"daily","scheduledTime":"09:00","workspaceId":"workspace_abc"}'
```
```json
{
  "success": true,
  "data": {
    "id": 2,
    "name": "Pause low ROAS ads",
    "status": "active",
    "flow": { "nodes": [ { "id": "trigger-1", "type": "trigger", "data": {} }, { "id": "action-1", "type": "action", "data": {} } ] },
    "actionType": "pause_ad",
    "accountId": "act_123456789",
    "frequency": "daily",
    "scheduledDate": "2026-02-27",
    "scheduledTime": "09:00",
    "workspaceId": "workspace_abc",
    "createdAt": "2026-02-27T15:00:00.000Z",
    "updatedAt": "2026-02-27T15:00:00.000Z"
  }
}
```

### Update Rule
- PATCH /v1/automations/:id
  Body: any combination of name, flow, actionType, accountId, targetId, newName, status, frequency, scheduledDate, scheduledTime, dayOfWeek, dayOfMonth, startDate, endDate, workspaceId. At least one field required.
```bash
curl -sS -X PATCH "https://api.admanage.ai/v1/automations/2" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'
```
```json
{
  "success": true,
  "data": {
    "id": 2,
    "name": "Pause low ROAS ads",
    "status": "paused",
    "frequency": "daily",
    "updatedAt": "2026-02-27T16:00:00.000Z"
  }
}
```

### Delete Rule
- DELETE /v1/automations/:id
```bash
curl -sS -X DELETE "https://api.admanage.ai/v1/automations/2" \
  -H "Authorization: Bearer <api_key>"
```
```json
{ "success": true, "message": "Rule 2 deleted" }
```

### Execute Rule by ID
- POST /v1/automations/:id/execute
  Runs an existing saved rule. Returns 202 Accepted with an executionId to poll.
```bash
curl -sS -X POST "https://api.admanage.ai/v1/automations/1/execute" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "executionId": 102,
    "status": "running",
    "message": "Poll GET /v1/automations/executions/102 for status."
  }
}
```

### Execute Inline (no saved rule)
- POST /v1/automations/execute
  Body: flow (required, object with nodes array), actionType (required), accountId (required), name?, targetId?, newName?, dryRun? (boolean), workspaceId?
  Returns 202 Accepted with an executionId to poll.
```bash
curl -sS -X POST "https://api.admanage.ai/v1/automations/execute" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"flow":{"nodes":[{"id":"action-1","type":"action","data":{}}]},"actionType":"pause_ad","accountId":"act_123456789","dryRun":true}'
```
```json
{
  "success": true,
  "data": {
    "executionId": 103,
    "status": "running",
    "message": "Poll GET /v1/automations/executions/103 for status."
  }
}
```

### List Executions
- GET /v1/automations/executions
  Query: page, limit, status ("running"|"completed"|"failed"|"scheduled_delay"|"awaiting_approval"), automationRuleId, workspaceId
```bash
curl -sS "https://api.admanage.ai/v1/automations/executions?page=1&limit=10&status=completed" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": [
    {
      "id": 101,
      "automationRuleId": 1,
      "name": "Pause low ROAS ads",
      "actionType": "pause_ad",
      "status": "completed",
      "executedAt": "2026-02-26T09:00:05.000Z",
      "completedAt": "2026-02-26T09:00:12.000Z",
      "duration": 7000,
      "errorMessage": null,
      "workspaceId": "workspace_abc"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
}
```

### Get Execution Details
- GET /v1/automations/executions/:id
  Returns full execution with stepResults, executionLogs, flow, and any delayedExecution or approval records.
```bash
curl -sS "https://api.admanage.ai/v1/automations/executions/101" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "id": 101,
    "automationRuleId": 1,
    "name": "Pause low ROAS ads",
    "actionType": "pause_ad",
    "accountId": "act_123456789",
    "flow": { "nodes": [] },
    "status": "completed",
    "executedAt": "2026-02-26T09:00:05.000Z",
    "completedAt": "2026-02-26T09:00:12.000Z",
    "duration": 7000,
    "stepResults": [
      { "nodeId": "action-1", "status": "success", "result": { "adsPaused": 3 } }
    ],
    "executionLogs": [ "Evaluating trigger...", "Running action: pause_ad", "Paused 3 ads" ],
    "errorMessage": null,
    "delayedExecution": null,
    "approval": null
  }
}
```

Notes:
- Execute endpoints return HTTP 202 Accepted. Most automations complete in seconds — poll the execution endpoint for final status.
- Status values: "running", "completed", "failed", "scheduled_delay" (waiting for delay node), "awaiting_approval" (pending human approval).
- Inline execute (POST /v1/automations/execute) runs a flow without saving it as a rule. Useful for one-off or CI-triggered automation.
- dryRun: true will simulate the execution without making real changes (supported on inline execute).
- All queries are scoped to the company associated with your API key.

## Launch Defaults
Get saved defaults for an ad account — Facebook Page, Instagram, ad copy, CTA, link, UTM tags, naming convention. Call this before launching to pre-fill values.

### GET /v1/launch-defaults
Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| accountId | no | Ad account ID (e.g. "act_123"). If omitted, uses the user's default ad account |
| workspaceId | no | Workspace ID. If omitted, uses the user's default workspace |

```bash
curl -sS "https://api.admanage.ai/v1/launch-defaults" \
  -H "Authorization: Bearer <api_key>"

# With specific account
curl -sS "https://api.admanage.ai/v1/launch-defaults?accountId=act_384730851257635" \
  -H "Authorization: Bearer <api_key>"
```
```json
{
  "success": true,
  "data": {
    "accountId": "act_384730851257635",
    "accountName": "Admanage Limited",
    "platform": "facebook",
    "workspaceId": "workspace_abc",
    "defaults": {
      "page": "470703006115773",
      "pageName": "Admanage",
      "insta": "17841471826052348",
      "instaName": "admanage.official",
      "title": "Stop wasting time on ad management",
      "description": "Launch ads 10x faster with AdManage",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "displaylink": "admanage.ai",
      "urlTags": "utm_source=facebook&utm_medium=paid",
      "naming": "{{campaign}} | {{adset}} | {{creative}}",
      "namingSeparator": " | ",
      "launchPaused": false
    }
  }
}
```

## Ad Formats (Carousel, Multi-Placement, Flexible)
The `type` field in each ad controls the format. Here are details for advanced formats:

### Carousel (type: "carousel")
2+ cards, each with its own headline, description, and link. Each media item can include per-card fields:
| Field | Description |
|-------|-------------|
| carouselTitle | Per-card headline |
| carouselDescription | Per-card description |
| carouselLink | Per-card click-through URL |
| carouselIndex | Card position (0-based) |

```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [{
      "adAccountId": "act_384730851257635",
      "type": "carousel",
      "title": "Our Best Products",
      "cta": "SHOP_NOW",
      "link": "https://example.com/",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "adSets": [{ "value": "120248289622780456", "label": "US Broad" }],
      "media": [
        { "url": "https://media.admanage.ai/acme/card1.png", "carouselTitle": "Product A", "carouselDescription": "Best seller", "carouselLink": "https://example.com/a", "carouselIndex": 0 },
        { "url": "https://media.admanage.ai/acme/card2.png", "carouselTitle": "Product B", "carouselDescription": "New arrival", "carouselLink": "https://example.com/b", "carouselIndex": 1 }
      ]
    }]
  }'
```

### Multi-Placement (type: "multi")
2+ format variants (square, vertical, landscape) in ONE ad. Facebook auto-picks the best per placement:
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [{
      "adAccountId": "act_384730851257635",
      "type": "multi",
      "title": "Spring Campaign",
      "cta": "LEARN_MORE",
      "link": "https://example.com/",
      "page": "470703006115773",
      "adSets": [{ "value": "120248289622780456", "label": "US Broad" }],
      "media": [
        { "url": "https://media.admanage.ai/acme/square-1x1.mp4" },
        { "url": "https://media.admanage.ai/acme/vertical-9x16.mp4" }
      ]
    }]
  }'
```

### Flexible / Advantage+ (type: "flexible")
Multiple headline and body variations — Facebook generates optimal combinations:
```bash
curl -sS -X POST "https://api.admanage.ai/v1/launch" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ads": [{
      "adAccountId": "act_384730851257635",
      "type": "flexible",
      "cta": "LEARN_MORE",
      "link": "https://example.com/",
      "page": "470703006115773",
      "headlineVariations": ["Stop wasting time", "Launch ads 10x faster", "The ad tool you need"],
      "bodyVariations": ["Try AdManage free", "Used by 500+ brands", "No credit card required"],
      "adSets": [{ "value": "120248289622780456", "label": "US Broad" }],
      "media": [
        { "url": "https://media.admanage.ai/acme/creative.mp4" }
      ]
    }]
  }'
```

## Top Ads (Performance)
Get top performing ads by spend, sorted by a metric.

### GET /v1/analytics/top-ads
Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| accountIds | yes | Comma-separated ad account IDs |
| startDate | yes | Start date (YYYY-MM-DD) |
| endDate | yes | End date (YYYY-MM-DD) |
| campaignIds | no | Comma-separated campaign IDs to filter |
| adSetIds | no | Comma-separated ad set IDs to filter |
| adType | no | Filter by type: "video", "image", "carousel" |
| limit | no | Max results (default 10, max 50) |
| page | no | Page number (default 1) |
| workspaceId | no | Workspace ID |

```bash
curl -sS "https://api.admanage.ai/v1/analytics/top-ads?accountIds=act_384730851257635&startDate=2026-03-01&endDate=2026-03-20&limit=5" \
  -H "Authorization: Bearer <api_key>"
```

## Media (Search + Upload)
Search uploaded media files and upload new media from URL or file.

### GET /v1/media/search
Search media files by name, type, or other criteria. Proxied to the main AdManage API.
```bash
curl -sS "https://api.admanage.ai/v1/media/search?query=spring&type=video" \
  -H "Authorization: Bearer <api_key>"
```

### GET /v1/media/:id
Get details of a specific media file.
```bash
curl -sS "https://api.admanage.ai/v1/media/12345" \
  -H "Authorization: Bearer <api_key>"
```

### POST /v1/media/upload/url
Upload media from a public URL to the AdManage library.
Body: { url }
```bash
curl -sS -X POST "https://api.admanage.ai/v1/media/upload/url" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video.mp4"}'
```

### POST /v1/media/upload
Upload a local file via multipart/form-data.
```bash
curl -sS -X POST "https://api.admanage.ai/v1/media/upload" \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@/path/to/creative.mp4"
```

## Cloud Storage (Google Drive + Dropbox)
Browse files in connected Google Drive and Dropbox accounts for launching.

### GET /v1/drive/browse
Browse Google Drive folders and files.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| folderId | no | Google Drive folder ID (default: "root") |
| scope | no | "my-drive" (default) or "shared-with-me" |
| search | no | Search query for file names |
| pageSize | no | Results per page (default 100) |
| pageToken | no | Pagination token from previous response |
| workspaceId | no | Workspace ID (auto-detected from user if omitted) |

```bash
# Browse root folder
curl -sS "https://api.admanage.ai/v1/drive/browse" \
  -H "Authorization: Bearer <api_key>"

# Browse a specific folder
curl -sS "https://api.admanage.ai/v1/drive/browse?folderId=1ABcDeFgHiJkLmNoP" \
  -H "Authorization: Bearer <api_key>"

# Search for files
curl -sS "https://api.admanage.ai/v1/drive/browse?search=spring%20campaign" \
  -H "Authorization: Bearer <api_key>"
```

### GET /v1/dropbox/browse
Browse Dropbox folders and shared links.

Query parameters:
| Param | Required | Description |
|-------|----------|-------------|
| path | no | Dropbox folder path (default: root "") |
| sharedLink | no | Dropbox shared folder/file link URL |
| search | no | Search query for file names |
| limit | no | Results per page (default 100) |
| workspaceId | no | Workspace ID (auto-detected from user if omitted) |

```bash
# Browse root folder
curl -sS "https://api.admanage.ai/v1/dropbox/browse" \
  -H "Authorization: Bearer <api_key>"

# Browse a subfolder
curl -sS "https://api.admanage.ai/v1/dropbox/browse?path=/Marketing/Creatives" \
  -H "Authorization: Bearer <api_key>"

# Browse a shared folder link
curl -sS "https://api.admanage.ai/v1/dropbox/browse?sharedLink=https://www.dropbox.com/scl/fo/abc123/AABcDE" \
  -H "Authorization: Bearer <api_key>"
```
Each file in the response includes a `launchUrl` — pass this directly as the `url` in media[] when launching ads.

## MCP Server (Model Context Protocol)
AdManage provides an MCP server for AI assistants like Claude. All 36+ API tools are available as MCP tools.

### Remote (Claude.ai / Claude Desktop / Claude Code)
```bash
claude mcp add --transport http admanage https://mcp.admanage.ai/mcp \
  --header "Authorization: Bearer ak_your_api_key"
```

### Local (Claude Code — stdio)
```bash
claude mcp add admanage \
  --transport stdio \
  -- npx tsx packages/mcp-admanage/src/index.ts \
  --env ADMANAGE_API_KEY=your_api_key \
  --env ADMANAGE_API_URL=https://api.admanage.ai
```

Endpoints:
- MCP: https://mcp.admanage.ai/mcp
- Health: https://mcp.admanage.ai/health
- Docs: https://api.admanage.ai/llms.txt