# Admanage API Docs

> Programmatic llms.txt generated from the public Admanage API docs catalog.

Admanage exposes APIs for launching, managing, measuring, and automating paid social advertising workflows.

## Core Resources

- [API docs](https://admanage.ai/api-docs)
- [API service llms.txt](https://api.admanage.ai/llms.txt)
- API base URL: https://api.admanage.ai
- Authentication: send your API key in the Authorization header as a Bearer token.

## Endpoint Index

### AdScan

- [Search AdScan Saved Ads By Spend](https://admanage.ai/api-docs/get-adscan-saved-ads-by-spend) - GET /v1/adscan/trpc/ads.list
- [Scrape Meta Ads Library URL](https://admanage.ai/api-docs/post-adscan-scrape) - POST /v1/adscan/scrape
- [Get AdScan Scrape Job Status](https://admanage.ai/api-docs/get-adscan-scrape-job) - GET /v1/adscan/scrape/{jobId}
- [AdScan Query Wrapper](https://admanage.ai/api-docs/get-adscan-query-wrapper) - GET /v1/adscan/trpc/{procedure}
- [AdScan Mutation Wrapper](https://admanage.ai/api-docs/post-adscan-mutation-wrapper) - POST /v1/adscan/trpc/{procedure}
- [List AdScan Boards](https://admanage.ai/api-docs/get-adscan-boards-list) - GET /v1/adscan/trpc/boards.list
- [Create AdScan Board](https://admanage.ai/api-docs/post-adscan-boards-create) - POST /v1/adscan/trpc/boards.create
- [Get AdScan Ad Details](https://admanage.ai/api-docs/get-adscan-ads-get-details) - GET /v1/adscan/trpc/ads.getDetails
- [Get Brand Spy Overview](https://admanage.ai/api-docs/get-adscan-brandspy-overview) - GET /v1/adscan/trpc/brandSpy.getOverview
- [List Followed AdScan Companies](https://admanage.ai/api-docs/get-adscan-companies-list-followed) - GET /v1/adscan/trpc/companies.listFollowed

### Accounts

- [Get Ad Accounts](https://admanage.ai/api-docs/get-adaccounts) - GET /v1/adaccounts
- [Get Profiles (Pages & Instagram)](https://admanage.ai/api-docs/get-profiles) - GET /v1/profiles
- [Get User Info](https://admanage.ai/api-docs/get-user-info) - GET /v1/user/extended2
- [Get Workspaces](https://admanage.ai/api-docs/get-workspaces) - GET /v1/workspaces
- [Update Launch Defaults](https://admanage.ai/api-docs/update-launch-defaults) - PATCH /v1/launch-defaults

### Templates

- [Get Ad Templates](https://admanage.ai/api-docs/get-ad-templates) - GET /v1/templates/ad-copy
- [Get Ad Template Copy Details](https://admanage.ai/api-docs/get-ad-template-by-id) - GET /v1/templates/ad-copy/{id}

### Performance

- [Get Campaigns](https://admanage.ai/api-docs/get-campaigns) - GET /v1/campaigns
- [Get Ad Sets](https://admanage.ai/api-docs/get-adsets) - GET /v1/adsets

### Batches

- [Get Ad Batches](https://admanage.ai/api-docs/get-adbatches) - GET /v1/adbatches
- [Get Ad Batch By ID](https://admanage.ai/api-docs/get-adbatch-by-id) - GET /v1/adbatches/{id}
- [Ad Delivery Statuses](https://admanage.ai/api-docs/ad-delivery-statuses) - GET /v1/adbatches/{id}/ad-delivery-statuses

### Launch Meta Ads

- [Launch Single Ads](https://admanage.ai/api-docs/post-launch) - POST /v1/launch
- [Boost Facebook Organic Post](https://admanage.ai/api-docs/post-launch-organic-facebook-post) - POST /v1/launch
- [Launch Multi-Placement Ads](https://admanage.ai/api-docs/post-launch-multi) - POST /v1/launch
- [Launch Carousel Ads](https://admanage.ai/api-docs/post-launch-carousel) - POST /v1/launch
- [Launch Flexible Ads](https://admanage.ai/api-docs/post-launch-flexible) - POST /v1/launch
- [Launch Ads From Draft](https://admanage.ai/api-docs/post-launch-from-draft) - POST /v1/launch/from-draft
- [Launch Meta Partnership Code Ads](https://admanage.ai/api-docs/post-launch-partnership-code) - POST /v1/launch
- [Check Batch Status](https://admanage.ai/api-docs/check-batch-status) - GET /v1/batch-status/{id}

### Launch TikTok Ads

- [Launch TikTok Ads](https://admanage.ai/api-docs/post-launch-tiktok) - POST /v1/launch
- [Launch TikTok Spark Ads](https://admanage.ai/api-docs/post-launch-tiktok-spark) - POST /v1/launch
- [Query TikTok Ad Account Metrics](https://admanage.ai/api-docs/get-tiktok-reports-query-channel) - GET /v1/reports/query

### Launch Snapchat Ads

- [Launch Snapchat Ads](https://admanage.ai/api-docs/post-launch-snapchat) - POST /v1/launch

### Launch Pinterest Ads

- [Launch Pinterest Ads](https://admanage.ai/api-docs/post-launch-pinterest) - POST /v1/launch
- [Query Pinterest Ad Account Metrics](https://admanage.ai/api-docs/get-pinterest-reports-query-channel) - GET /v1/reports/query

### Launch Axon Ads

- [Launch Axon/AppLovin Ads](https://admanage.ai/api-docs/post-launch-axon) - POST /v1/launch

### Launch Taboola Ads

- [Launch Taboola Ads](https://admanage.ai/api-docs/post-launch-taboola) - POST /v1/launch

### Launch LinkedIn Ads

- [Launch LinkedIn Ads](https://admanage.ai/api-docs/post-launch-linkedin) - POST /v1/launch

### Reports

- [Query Reports](https://admanage.ai/api-docs/get-reports-query) - GET /v1/reports/query
- [Query Meta Ad Account Metrics](https://admanage.ai/api-docs/get-reports-query-meta) - GET /v1/reports/query
- [Query Google Ads Account Metrics](https://admanage.ai/api-docs/get-reports-query-google) - GET /v1/reports/query
- [Query TikTok Ad Account Metrics](https://admanage.ai/api-docs/get-reports-query-tiktok) - GET /v1/reports/query
- [Query Pinterest Ad Account Metrics](https://admanage.ai/api-docs/get-reports-query-pinterest) - GET /v1/reports/query
- [Get Report Fields](https://admanage.ai/api-docs/get-reports-fields) - GET /v1/reports/fields
- [Get Meta Reach Composition](https://admanage.ai/api-docs/get-meta-reach-composition) - GET /v1/reports/meta/reach-composition
- [Get Meta Country Breakdown](https://admanage.ai/api-docs/get-meta-country-breakdown) - GET /v1/reports/meta/country-breakdown

### Drafts

- [Create Launch Draft](https://admanage.ai/api-docs/create-draft) - POST /v1/drafts
- [List Launch Drafts](https://admanage.ai/api-docs/list-drafts) - GET /v1/drafts
- [Get Launch Draft By ID](https://admanage.ai/api-docs/get-draft-by-id) - GET /v1/drafts/{id}
- [Update Launch Draft](https://admanage.ai/api-docs/update-draft) - PATCH /v1/drafts/{id}
- [Delete Launch Draft](https://admanage.ai/api-docs/delete-draft) - DELETE /v1/drafts/{id}
- [Launch Draft](https://admanage.ai/api-docs/launch-draft) - POST /v1/drafts/{id}/launch

### Uploading Media

- [Upload Media](https://admanage.ai/api-docs/upload-media) - POST /v1/media/upload
- [Upload Media From URL](https://admanage.ai/api-docs/upload-media-from-url) - POST /v1/media/upload/url
- [Check Media Filename](https://admanage.ai/api-docs/check-media-duplicate) - POST /v1/media/upload/check
- [Search Stored Media](https://admanage.ai/api-docs/search-connect-media) - GET /v1/media/search
- [Get Stored Media By ID](https://admanage.ai/api-docs/get-connect-media) - GET /v1/media/{id}
- [Get Upload URL](https://admanage.ai/api-docs/get-upload-url) - POST /v1/media/get-upload-url
- [Confirm Upload](https://admanage.ai/api-docs/confirm-upload) - POST /v1/media/confirm-upload
- [Generate Thumbnail](https://admanage.ai/api-docs/generate-thumbnail) - POST /v1/media/generate-thumbnail
- [Browse Google Drive](https://admanage.ai/api-docs/browse-google-drive) - GET /v1/drive/browse
- [Browse Dropbox](https://admanage.ai/api-docs/browse-dropbox) - GET /v1/dropbox/browse

### Library

- [List Library Assets](https://admanage.ai/api-docs/list-library-assets) - GET /v1/library/assets
- [Get Library Asset](https://admanage.ai/api-docs/get-library-asset) - GET /v1/library/assets/{id}
- [List Library Boards](https://admanage.ai/api-docs/list-library-boards) - GET /v1/library/boards
- [List Board Assets](https://admanage.ai/api-docs/list-library-board-assets) - GET /v1/library/boards/{id}/assets
- [List Library Tags](https://admanage.ai/api-docs/list-library-tags) - GET /v1/library/tags
- [Update Library Asset](https://admanage.ai/api-docs/update-library-asset) - POST /v1/library/assets/{id}/update
- [Create Library Board](https://admanage.ai/api-docs/create-library-board) - POST /v1/library/boards
- [Add Asset to Board](https://admanage.ai/api-docs/add-asset-to-board) - POST /v1/library/boards/{id}/assets
- [Remove Asset from Board](https://admanage.ai/api-docs/remove-asset-from-board) - DELETE /v1/library/boards/{id}/assets

### Manage Meta Ads

- [Query Meta Ad Account Metrics](https://admanage.ai/api-docs/get-meta-reports-query-channel) - GET /v1/reports/query
- [Create Meta Campaign](https://admanage.ai/api-docs/create-campaign) - POST /v1/manage/create-campaign
- [Create Meta Ad Set](https://admanage.ai/api-docs/create-adset) - POST /v1/manage/create-adset
- [Duplicate Ad Set](https://admanage.ai/api-docs/duplicate-adset) - POST /v1/manage/duplicate-adset
- [Duplicate Campaign](https://admanage.ai/api-docs/duplicate-campaign) - POST /v1/manage/duplicate-campaign
- [Duplicate Ad](https://admanage.ai/api-docs/duplicate-ad) - POST /v1/manage/duplicate-ad
- [Get Change History](https://admanage.ai/api-docs/get-changes) - GET /v1/manage/changes
- [List Ads in Ad Set](https://admanage.ai/api-docs/list-ads) - GET /v1/manage/list-ads
- [Pause, Resume, or End Ads / Ad Sets / Campaigns](https://admanage.ai/api-docs/update-status) - POST /v1/manage/update-status
- [Update Campaign Budget](https://admanage.ai/api-docs/update-campaign-budget) - POST /v1/manage/update-campaign-budget
- [Update Ad Set Budget](https://admanage.ai/api-docs/update-adset-budget) - POST /v1/manage/update-adset-budget
- [Update Campaign Bidding](https://admanage.ai/api-docs/update-campaign-bidding) - POST /v1/manage/update-campaign-bidding
- [Update Ad Set Bidding](https://admanage.ai/api-docs/update-adset-bidding) - POST /v1/manage/update-adset-bidding
- [Update Ad Set ZIP Targeting](https://admanage.ai/api-docs/update-adset-zip-targeting) - POST /v1/manage/update-adset-zip-targeting
- [Edit Existing Ads](https://admanage.ai/api-docs/edit-ads) - POST /v1/manage/edit-ads
- [List Lead Forms](https://admanage.ai/api-docs/lead-forms) - GET /v1/manage/lead-forms
- [Refresh Ad Sets](https://admanage.ai/api-docs/refresh-adsets) - POST /v1/manage/refresh-adsets
- [Duplicate Ad Set (Advanced)](https://admanage.ai/api-docs/duplicate-adset-advanced) - POST /v1/manage/duplicate-adset-advanced
- [Delete Ads / Ad Sets / Campaigns](https://admanage.ai/api-docs/delete-entities) - POST /v1/manage/delete

### Manage Snapchat Ads

- [Create Snapchat Campaign](https://admanage.ai/api-docs/create-snapchat-campaign) - POST /v1/manage/snapchat/create-campaign
- [Create Snapchat Ad Squad](https://admanage.ai/api-docs/create-snapchat-adsquad) - POST /v1/manage/snapchat/create-adsquad
- [List Snapchat Campaigns](https://admanage.ai/api-docs/get-snapchat-campaigns) - GET /v1/manage/snapchat/campaigns
- [List Snapchat Ad Squads](https://admanage.ai/api-docs/get-snapchat-adsquads) - GET /v1/manage/snapchat/adsquads
- [List Snapchat Ads](https://admanage.ai/api-docs/get-snapchat-ads) - GET /v1/manage/snapchat/ads

### Manage LinkedIn Ads

- [List LinkedIn Ad Accounts](https://admanage.ai/api-docs/get-linkedin-accounts) - GET /v1/linkedin/accounts
- [Query LinkedIn Campaign Groups, Campaigns, or Creatives](https://admanage.ai/api-docs/get-linkedin-manage) - GET /v1/linkedin/manage
- [List LinkedIn Organization Posts](https://admanage.ai/api-docs/get-linkedin-organization-posts) - GET /v1/linkedin/organization-posts
- [Duplicate LinkedIn Campaign Group](https://admanage.ai/api-docs/post-linkedin-duplicate-campaign) - POST /v1/linkedin/duplicate-campaign
- [Duplicate LinkedIn Campaign](https://admanage.ai/api-docs/post-linkedin-duplicate-adgroup) - POST /v1/linkedin/duplicate-adgroup

### Manage Axon Ads

- [Duplicate Axon Campaign](https://admanage.ai/api-docs/axon-duplicate-campaign) - POST /v1/manage/axon/duplicate-campaign

### Automations

- [List Automation Rules](https://admanage.ai/api-docs/list-automations) - GET /v1/automations
- [Get Automation Rule](https://admanage.ai/api-docs/get-automation) - GET /v1/automations/{id}
- [Create Automation Rule](https://admanage.ai/api-docs/create-automation) - POST /v1/automations
- [Update Automation Rule](https://admanage.ai/api-docs/update-automation) - PATCH /v1/automations/{id}
- [Delete Automation Rule](https://admanage.ai/api-docs/delete-automation) - DELETE /v1/automations/{id}
- [Execute Automation Rule](https://admanage.ai/api-docs/execute-automation) - POST /v1/automations/{id}/execute
- [Execute Inline Automation](https://admanage.ai/api-docs/execute-automation-inline) - POST /v1/automations/execute
- [List Automation Executions](https://admanage.ai/api-docs/list-automation-executions) - GET /v1/automations/executions
- [Get Automation Execution](https://admanage.ai/api-docs/get-automation-execution) - GET /v1/automations/executions/{id}
- [Preview Automation Trigger](https://admanage.ai/api-docs/preview-automation-trigger) - GET /v1/automations/preview-trigger

### Spend

- [Get Daily Ad Spend](https://admanage.ai/api-docs/get-daily-spend) - GET /v1/spend/daily

### Comments

- [Get Comments](https://admanage.ai/api-docs/get-comments) - GET /v1/comments
- [Get Comment Analytics](https://admanage.ai/api-docs/get-comments-analytics) - GET /v1/comments/analytics
- [Reply to Comment](https://admanage.ai/api-docs/reply-to-comment) - POST /v1/comments/reply
- [Hide Comment](https://admanage.ai/api-docs/hide-comment) - POST /v1/comments/hide

### Analytics

- [Top Ads](https://admanage.ai/api-docs/get-analytics-top-ads) - GET /v1/analytics/top-ads

### Activity Log

- [List Activity Log Entries](https://admanage.ai/api-docs/list-activity-log) - GET /v1/activity
- [Get Activity Log Entry](https://admanage.ai/api-docs/get-activity-log-entry) - GET /v1/activity/{id}

### Changelog

- [List Changelog Entries](https://admanage.ai/api-docs/get-changelog) - GET /api/external/crm
- [Create Changelog Entry](https://admanage.ai/api-docs/post-changelog) - POST /api/external/crm
- [Get Changelog Entry](https://admanage.ai/api-docs/get-changelog-entry) - GET /api/external/crm/{id}
- [Update Changelog Entry](https://admanage.ai/api-docs/patch-changelog-entry) - PATCH /api/external/crm/{id}
- [Delete Changelog Entry](https://admanage.ai/api-docs/delete-changelog-entry) - DELETE /api/external/crm/{id}
- [Generate Cover Image](https://admanage.ai/api-docs/post-changelog-generate-image) - POST /api/external/crm/generate-image

### Conversions

- [List Pixels](https://admanage.ai/api-docs/get-conversions-pixels) - GET /v1/conversions/pixels
- [Send Conversion Events](https://admanage.ai/api-docs/post-conversions-events) - POST /v1/conversions/events

### Google Ads

- [Query Google Ads Account Metrics](https://admanage.ai/api-docs/get-google-ads-reports-query-channel) - GET /v1/reports/query
- [List Google Ads Campaigns](https://admanage.ai/api-docs/google-ads-campaigns) - GET /v1/google-ads/campaigns
- [Toggle Campaign Status](https://admanage.ai/api-docs/google-ads-toggle-status) - POST /v1/google-ads/campaigns/toggle-status
- [Rename Campaign](https://admanage.ai/api-docs/google-ads-rename) - POST /v1/google-ads/campaigns/rename
- [Duplicate Campaign](https://admanage.ai/api-docs/google-ads-duplicate-campaign) - POST /v1/google-ads/duplicate-campaign
- [Duplicate Ad Group](https://admanage.ai/api-docs/google-ads-duplicate-ad-group) - POST /v1/google-ads/duplicate-ad-group
- [Duplicate Ad](https://admanage.ai/api-docs/google-ads-duplicate-ad) - POST /v1/google-ads/duplicate-ad
- [Get Ad Details](https://admanage.ai/api-docs/google-ads-ad-details) - POST /v1/google-ads/ad-details
- [Add Text Assets](https://admanage.ai/api-docs/google-ads-add-text-assets) - POST /v1/google-ads/add-text-assets
- [Add Video/Image Assets](https://admanage.ai/api-docs/google-ads-add-assets) - POST /v1/google-ads/add-assets
- [Remove Asset](https://admanage.ai/api-docs/google-ads-remove-assets) - POST /v1/google-ads/remove-assets
- [Update Assets](https://admanage.ai/api-docs/google-ads-update-assets) - POST /v1/google-ads/update-assets
- [Launch (Google Ads)](https://admanage.ai/api-docs/google-ads-launch) - POST /v1/google-ads/launch

### YouTube

- [Upload Video to YouTube](https://admanage.ai/api-docs/youtube-upload) - POST /v1/youtube/upload-from-url

### Google Sheets

- [Read Google Sheet](https://admanage.ai/api-docs/read-google-sheet) - GET /v1/sheets/read

## Endpoint Details

### Search AdScan Saved Ads By Spend
Docs: https://admanage.ai/api-docs/get-adscan-saved-ads-by-spend
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/ads.list
Category: AdScan
Mutating: no
Search saved AdScan ads with a spend-style filter. AdManage accepts spend/spendMin/spendMax and converts them to AdScan's viewsMin/viewsMax using a fixed $13 CPM assumption.

Query example:
input=%7B%22searchQuery%22%3A%22crypto%22%2C%22spendMin%22%3A260%2C%22spendMax%22%3A520%2C%22limit%22%3A10%7D

Notes:
- This is a convenience wrapper over AdScan ads.list.
- spend and spendMin are treated as minimum estimated spend in USD.
- spendMax is treated as maximum estimated spend in USD.
- Conversion uses a fixed $13 CPM assumption: views = spend * 1000 / 13.
- You can combine spend filtering with searchQuery, boardId, cursor, and limit.

### Scrape Meta Ads Library URL
Docs: https://admanage.ai/api-docs/post-adscan-scrape
Method: POST
Path: https://api.admanage.ai/v1/adscan/scrape
Category: AdScan
Mutating: yes
Enqueue a scrape of a Meta Ads Library URL (or any advertiser search input). Returns a jobId immediately; poll GET /v1/adscan/scrape/{jobId} until status is 'success' or 'failed'.

Request body example:
```json
{
  "url": "https://www.facebook.com/ads/library/?view_all_page_id=123456789&country=US"
}
```

Notes:
- Pass { url } as shorthand — the URL must include a numeric view_all_page_id query param.
- Or pass the full shape: { mode: 'url' | 'search' | 'advertiserId', input, country?, priority?, maxAds? }.
- country defaults to 'GB' and accepts 'US' or 'GB'. For URL mode, a country=... query param in the URL overrides the body value.
- priority accepts 'urgent' | 'high' | 'normal' and defaults to 'urgent' — scrapes submitted through this endpoint jump the queue ahead of UI-initiated high-priority jobs.
- maxAds caps the scrape at N ads (range 1–1000, default 100). Smaller caps finish much faster — raise it when the user asks for exhaustive coverage.
- deduped=true means a queued job for this advertiser/country already exists and was returned instead of creating a new one.
- Available to any authenticated AdManage / AdScan Pro user with an API key. Scrapes typically take seconds to a few minutes depending on ad count.
- Rate limit: 20 scrapes per 24 hours per user. The response includes a rateLimit object with scrapesUsed, scrapesPerDay, and scrapesRemaining. When exceeded, the endpoint returns 429 TOO_MANY_REQUESTS.

### Get AdScan Scrape Job Status
Docs: https://admanage.ai/api-docs/get-adscan-scrape-job
Method: GET
Path: https://api.admanage.ai/v1/adscan/scrape/{jobId}
Category: AdScan
Mutating: no
Look up the status of a scrape job enqueued via POST /v1/adscan/scrape. Poll this endpoint until isTerminal is true, then fetch the resulting ads via /v1/adscan/trpc/ads.list filtered by advertiserId.

Notes:
- status values: 'queued' → 'running' → 'success' or 'failed'. isTerminal is true for 'success' and 'failed'.
- When status is 'success', use GET /v1/adscan/trpc/ads.list with input filter { advertiserId } to fetch the scraped ads.
- errorMessage is populated when status is 'failed'. Job may retry automatically up to maxRetries times.
- Available to any authenticated AdManage / AdScan Pro user with an API key.

### AdScan Query Wrapper
Docs: https://admanage.ai/api-docs/get-adscan-query-wrapper
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/{procedure}
Category: AdScan
Mutating: no
Proxy any AdScan tRPC query through AdManage using your AdManage API key. Replace {procedure} with a read procedure such as boards.list, ads.list, ads.getDetails, brandSpy.getOverview, or brandSpy.listTopAdvertisers.

Query example:
input=%7B%22searchQuery%22%3A%22crypto%22%2C%22spendMin%22%3A260%2C%22limit%22%3A5%7D

Notes:
- Preserves AdScan's native response shape — existing AdScan clients work with a base-URL swap.
- Use GET with a URL-encoded `input` query param exactly like AdScan's public tRPC API.
- See the AdScan procedure index at the top of this section for the full list of supported queries grouped by router (boards, ads, brandSpy, companies, notifications, teams, trending).
- AdManage injects the authenticated user's email upstream so AdScan data stays scoped to the caller.
- For ads.list, you can pass spend, spendMin, or spendMax — AdManage converts them to viewsMin/viewsMax using a fixed $13 CPM assumption.
- To scrape a Meta Ads Library URL on demand, prefer the dedicated POST /v1/adscan/scrape + GET /v1/adscan/scrape/{jobId} endpoints.

### AdScan Mutation Wrapper
Docs: https://admanage.ai/api-docs/post-adscan-mutation-wrapper
Method: POST
Path: https://api.admanage.ai/v1/adscan/trpc/{procedure}
Category: AdScan
Mutating: yes
Proxy any AdScan tRPC mutation through AdManage. Replace {procedure} with a write procedure such as boards.create, boards.update, ads.addToBoard, companies.follow, or notifications.upsertRule.

Request body example:
```json
{
  "name": "Competitor Winners"
}
```

Notes:
- Use POST with the same JSON body that AdScan expects for the target mutation.
- See the AdScan procedure index at the top of this section for supported mutations grouped by router.
- Read-only API keys are blocked at this endpoint with a 403 — use a read/write key for mutations.
- To scrape a Meta Ads Library URL on demand, prefer the dedicated POST /v1/adscan/scrape endpoint instead of calling brandSpy.enqueueScrape through the raw proxy.

### List AdScan Boards
Docs: https://admanage.ai/api-docs/get-adscan-boards-list
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/boards.list
Category: AdScan
Mutating: no
List the caller's AdScan saved-ads boards (own boards plus team boards). Returns a hierarchy with parent/child relationships and per-board edit/delete permissions.

Notes:
- No input required — boards are scoped to the authenticated AdManage user via X-User-Email.
- Team boards appear when the caller is a member of the owning team.
- Use the returned `id` with ads.list `boardId` filter or with ads.addToBoard / ads.removeFromBoard.

### Create AdScan Board
Docs: https://admanage.ai/api-docs/post-adscan-boards-create
Method: POST
Path: https://api.admanage.ai/v1/adscan/trpc/boards.create
Category: AdScan
Mutating: yes
Create a new AdScan saved-ads board for the caller, optionally nested under a parent or scoped to a team.

Request body example:
```json
{
  "name": "Competitor Winners"
}
```

Notes:
- `name` (required): board display name. The slug is auto-generated and made unique.
- `parentId` (optional): existing board id — creates the new board as a child.
- `teamId` (optional): create as a team board. Caller must be a member of the team.
- Read-only AdManage API keys are rejected with a 403.

### Get AdScan Ad Details
Docs: https://admanage.ai/api-docs/get-adscan-ads-get-details
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/ads.getDetails
Category: AdScan
Mutating: no
Fetch the full ad payload for a single AdScan ad — copy, media, advertiser, demographics, engagement, inferred tags, and US rank snapshot.

Query example:
input=%7B%22id%22%3A634033%7D

Notes:
- Provide either `id` (numeric AdScan ad id) or `hash` (platform-native id). Returns null when neither resolves.
- Response shape matches AdScan's native ads.getDetails output verbatim.
- Heavy payload — use ads.list for browsing and call this only when rendering a single ad.

### Get Brand Spy Overview
Docs: https://admanage.ai/api-docs/get-adscan-brandspy-overview
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/brandSpy.getOverview
Category: AdScan
Mutating: no
Aggregate Brand Spy snapshot for an advertiser — total ads, reach, top landing pages, top ads by reach, demographics, and scraper schedule status.

Query example:
input=%7B%22companyName%22%3A%22Metrotile+UK+Ltd%22%7D

Notes:
- `companyName` (required): advertiser name, matched case-insensitively (`ILIKE`).
- Optional filters: `dateFrom`, `dateTo` (ISO date), `status` ('active'|'inactive'|'all'), `mediaType` ('image'|'video'|'all'), `language`.
- `scraperStatus` differentiates 'never scheduled' / 'never succeeded' / 'last job failed' so you can render the right empty state.
- Total spend is 0 — Brand Spy doesn't track spend; use the views fields and apply your own CPM if needed.

### List Followed AdScan Companies
Docs: https://admanage.ai/api-docs/get-adscan-companies-list-followed
Method: GET
Path: https://api.admanage.ai/v1/adscan/trpc/companies.listFollowed
Category: AdScan
Mutating: no
List advertisers the caller has followed in AdScan, ordered most-recently-followed first, with pre-aggregated ad counts and view totals from the top-advertisers materialised view.

Notes:
- No input required — scoped to the authenticated user via X-User-Email.
- `totalSpend` is derived from `totalViews` using the AdScan spend formula and is delayed by ~15 min (matview refresh).
- Use companies.follow / companies.unfollow to mutate this list.

### Get Ad Accounts
Docs: https://admanage.ai/api-docs/get-adaccounts
Method: GET
Path: https://api.admanage.ai/v1/adaccounts
Category: Accounts
Mutating: no
List ad accounts available to the authenticated company.

Query example:
page=1&limit=25

### Get Profiles (Pages & Instagram)
Docs: https://admanage.ai/api-docs/get-profiles
Method: GET
Path: https://api.admanage.ai/v1/profiles
Category: Accounts
Mutating: no
Fetch Facebook Pages, Instagram accounts, and Threads profiles. Use the pageId values as the 'page' (Facebook) and 'insta' (Instagram) fields when launching ads, and pass pageName as facebookName/instaName so AdManage displays readable profile chips. Falls back to live Facebook Graph API if the DB cache is empty.

Query example:
businessId=act_123456789

Notes:
- All query params are optional. Omit everything to list all profiles for your company.
- businessId: filter by ad account. workspaceId is auto-discovered if omitted.
- type: filter by 'facebook', 'instagram', or 'threads'.
- refresh=true: bypass cache and fetch live from Facebook Graph API.
- Use pageId from type='facebook' as the 'page' field and pageName as the 'facebookName' field in launch requests.
- Use pageId from type='instagram' as the 'insta' field and pageName as the 'instaName' field in launch requests.

### Get User Info
Docs: https://admanage.ai/api-docs/get-user-info
Method: GET
Path: https://api.admanage.ai/v1/user/extended2
Category: Accounts
Mutating: no
Return user profile, organizations, workspaces, and ad-account settings.

### Get Workspaces
Docs: https://admanage.ai/api-docs/get-workspaces
Method: GET
Path: https://api.admanage.ai/v1/workspaces
Category: Accounts
Mutating: no
List all workspaces in the authenticated company.

Query example:
page=1&limit=25

### Get Ad Templates
Docs: https://admanage.ai/api-docs/get-ad-templates
Method: GET
Path: https://api.admanage.ai/v1/templates/ad-copy
Category: Templates
Mutating: no
List ad-copy templates with pagination.

Query example:
page=1&pageSize=10

### Get Ad Template Copy Details
Docs: https://admanage.ai/api-docs/get-ad-template-by-id
Method: GET
Path: https://api.admanage.ai/v1/templates/ad-copy/{id}
Category: Templates
Mutating: no
Fetch one ad template with detailed copy fields and generated copy rows.

### Get Campaigns
Docs: https://admanage.ai/api-docs/get-campaigns
Method: GET
Path: https://api.admanage.ai/v1/campaigns
Category: Performance
Mutating: no
List campaigns aggregated from ad sets by company.

Query example:
page=1&limit=25&platform=facebook&adAccountId=act_123456789

### Get Ad Sets
Docs: https://admanage.ai/api-docs/get-adsets
Method: GET
Path: https://api.admanage.ai/v1/adsets
Category: Performance
Mutating: no
List ad sets with status, spend, and ad count. Each ad set includes value and label fields so you can pass them directly into ads[].adSets[] when launching. Results are served from a local snapshot that auto-refreshes from the Meta Graph API when stale (older than 60 minutes) and after any ad-set mutation.

Query example:
page=1&limit=25&campaignId=1200123000999&platform=facebook&adAccountId=act_123456789&refresh=true

Notes:
- Use adAccountId as the preferred public filter parameter.
- businessId is also accepted as a compatibility alias and resolves to the same account lookup.
- Each ad set includes value and label — pass the object directly into your launch request's adSets array.
- Filter by accountId to list all ad sets for an account, or by campaignId to drill into a campaign.
- Freshness (Meta only): the local snapshot auto-refreshes from the Meta Graph API when it is older than 60 minutes, and is also invalidated after create-adset, duplicate-adset, duplicate-adset-advanced, update-status, update-adset-budget, update-adset-bidding, and delete on adsets/campaigns. The next call re-fetches from Meta.
- refresh=true (optional): forces a live Meta fetch before reading, regardless of staleness. Requires a single ad account in scope (accountId filter, or workspaceId scoped to one account). Meta only — ignored for other platforms.
- Response includes a `freshness` object: `{ refreshed, refreshedAccountIds, lastRefreshedAt }` so you can tell how current the data is.

### Get Ad Batches
Docs: https://admanage.ai/api-docs/get-adbatches
Method: GET
Path: https://api.admanage.ai/v1/adbatches
Category: Batches
Mutating: no
Paginated list of launch batches (recent launch history).

Query example:
page=1&limit=35&search=prospecting&workspaceId=workspace_abc&privateHistory=true

### Get Ad Batch By ID
Docs: https://admanage.ai/api-docs/get-adbatch-by-id
Method: GET
Path: https://api.admanage.ai/v1/adbatches/{id}
Category: Batches
Mutating: no
Fetch a specific batch by numeric ID or slug, including creativeState.

### Launch Single Ads
Docs: https://admanage.ai/api-docs/post-launch
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Create an ad batch and dispatch to the launcher service. Supports Meta, TikTok, Snapchat, Pinterest, Axon, and Taboola. Each ad is self-contained with its own account, ad sets, and media. Set adAccountType to specify the platform. Returns immediately with batch ID for async polling.

Request body example:
```json
{
  "ads": [
    {
      "adName": "AdManage API Docs - Creative 1",
      "adAccountId": "act_384730851257635",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "Launch ads faster with AdManage",
      "description": "Simple API launch test",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "page": "470703006115773",
      "facebookName": "Admanage",
      "insta": "17841471826052348",
      "instaName": "admanage.official",
      "adSets": [
        {
          "value": "120249198609970456",
          "label": "ABO - PRATH - V7"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
        }
      ]
    },
    {
      "adName": "AdManage API Docs - Creative 2",
      "adAccountId": "act_384730851257635",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "Speed matters for media buyers",
      "description": "Second creative variation",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "page": "470703006115773",
      "facebookName": "Admanage",
      "insta": "17841471826052348",
      "instaName": "admanage.official",
      "adSets": [
        {
          "value": "120249198609970456",
          "label": "ABO - PRATH - V7"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
        }
      ],
      "promoCode": "SAVE10"
    }
  ]
}
```

Notes:
- Returns 202 Accepted — the launch is asynchronous.
- Poll GET /v1/batch-status/{adBatchId} to track progress.
- Supports Facebook, TikTok, Snapchat, Pinterest, and Axon platforms.
- Each ad is self-contained: platform, adAccountId, adSets, and media are specified per ad.
- The default example is prefilled with the Admanage workspace/account values used in the dashboard, not placeholder IDs.
- Legacy format with "creativeState" wrapper is still supported for backwards compatibility.
- Set type to "single" (default), "multi", "carousel", or "flexible" per ad.
- adSets must be an array of objects with at least { value, label }. String IDs like ["123"] are also accepted and auto-normalized.
- Get adSets from GET /v1/adsets — the response includes value and label fields ready to pass directly.
- Get page/insta IDs and display names from GET /v1/launch-defaults or GET /v1/profiles?businessId=act_xxx.
- For Meta display clarity, pass facebookName and instaName when available. They are optional for delivery but keep AdManage UI chips from falling back to truncated numeric IDs.
- The media field accepts both videos and images. Images use type: "image" (auto-detected from extension: .png, .jpg, .gif, .webp).
- If you uploaded media via POST /v1/media/upload, you can pass the returned url directly in media[].url.
- adSets can also be specified at the top level of the request body (outside ads[]) to apply the same ad sets to all ads.
- Typical workflow: GET /v1/adaccounts → GET /v1/profiles → GET /v1/adsets → POST /v1/launch.
- promoCode (optional, Meta only): Set a coupon/promo code per ad. Must contain at least 2 letters. Allowed characters: letters, numbers, dash, underscore. Example: "SAVE10".
- To boost an existing Facebook organic Page post, use the "Boost Facebook Organic Post" recipe: pass media[].effectiveStoryId and scalePostId: true.

### Boost Facebook Organic Post
Docs: https://admanage.ai/api-docs/post-launch-organic-facebook-post
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Meta only. Turn an existing organic Facebook Page post into an ad by launching with the post's object story ID. This reuses the organic post instead of uploading new media, while still letting you set the ad set, CTA, destination URL, and optional copy overrides.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Boost organic post - Spring launch",
      "adAccountId": "act_384730851257635",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "type": "single",
      "title": "Optional headline override",
      "description": "Optional primary text override",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "page": "470703006115773",
      "facebookName": "Admanage",
      "insta": "17841471826052348",
      "instaName": "admanage.official",
      "scalePostId": true,
      "launchPaused": true,
      "adSets": [
        {
          "value": "120249198609970456",
          "label": "US Broad 25-44"
        }
      ],
      "media": [
        {
          "effectiveStoryId": "470703006115773_122123456789012345",
          "existingAd": true,
          "existingMetaAd": true,
          "isExistingPost": true,
          "platform": "Web",
          "type": "image",
          "url": "https://www.facebook.com/470703006115773/posts/122123456789012345",
          "thumbnail": "https://media.admanage.ai/acme/facebook-post-preview.jpg",
          "adCopyDescription": "Original organic post caption"
        }
      ]
    }
  ]
}
```

Notes:
- Use this when the organic Facebook Page post already exists and you want the ad creative to reference that post.
- media[].effectiveStoryId is the delivery key. Facebook object story IDs usually use {page_id}_{post_id}. If Graph returns a bare post ID, prefix it with the owning Page ID.
- Set scalePostId: true so AdManage creates the Meta creative with object_story_id instead of uploading media.
- Set media[].existingAd, media[].existingMetaAd, and media[].isExistingPost to true so the launcher keeps the post-reuse path.
- The ad-level page should match the Facebook Page that owns the organic post.
- url and thumbnail are useful for AdManage previews, but Meta delivery depends on effectiveStoryId.
- For website or sales ad sets, the reused organic post must already be a link/CTA post with an external destination. Meta rejects image-only organic posts in those objectives even if the API payload includes cta and link.
- cta and link should match the reused post's CTA and destination where Meta allows a CTA on the reused post creative.
- Poll GET /v1/batch-status/{adBatchId} until the async launch finishes.

### Launch Multi-Placement Ads
Docs: https://admanage.ai/api-docs/post-launch-multi
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Meta only. Launch a multi-placement ad with multiple media items. Each media item becomes a separate placement (e.g. Feed, Story, Reel).

Request body example:
```json
{
  "ads": [
    {
      "adName": "Multi-Placement Spring Sale",
      "adAccountId": "act_123456789",
      "type": "multi",
      "title": "Spring Sale",
      "description": "Shop our collection",
      "cta": "SHOP_NOW",
      "link": "https://example.com",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "adSets": [
        {
          "value": "120012345678901234",
          "label": "US Broad 25-44"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
        },
        {
          "url": "https://media.admanage.ai/admanage.ai/2retest_edemo1hhjLNgl7.mp4"
        },
        {
          "url": "https://media.admanage.ai/admanage.ai/PT-Desk-Ad-David.mp4"
        }
      ]
    }
  ]
}
```

Notes:
- This ad type is Meta (Facebook/Instagram) only.
- Set type to "multi" for multi-placement ads.
- Each media item maps to a different placement (Feed, Story, Reel, etc.).
- The platform assigns placements based on media aspect ratios.

### Launch Carousel Ads
Docs: https://admanage.ai/api-docs/post-launch-carousel
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Meta only. Launch a carousel ad with multiple swipeable cards. Each media item becomes one card in the carousel.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Carousel - Product Lineup",
      "adAccountId": "act_123456789",
      "type": "carousel",
      "title": "Spring Collection",
      "description": "Swipe to explore",
      "cta": "SHOP_NOW",
      "link": "https://example.com",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "adSets": [
        {
          "value": "120012345678901234",
          "label": "US Broad 25-44"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/card-1.jpg",
          "carouselTitle": "Product A",
          "carouselDescription": "Best seller",
          "carouselLink": "https://example.com/products/a",
          "carouselIndex": 0
        },
        {
          "url": "https://media.admanage.ai/admanage.ai/card-2.mp4",
          "carouselTitle": "Product B",
          "carouselDescription": "New arrival",
          "carouselLink": "https://example.com/products/b",
          "carouselIndex": 1
        },
        {
          "url": "https://media.admanage.ai/admanage.ai/card-3.jpg",
          "carouselTitle": "Product C",
          "carouselIndex": 2
        }
      ]
    }
  ]
}
```

Notes:
- This ad type is Meta (Facebook/Instagram) only.
- Set type to "carousel" for carousel ads.
- Each media item becomes one swipeable card and must include carouselTitle.
- carouselDescription is optional per card.
- carouselLink is optional per card and falls back to the ad-level link when omitted.
- Card order follows the media array. carouselIndex is optional metadata if you want to label positions explicitly.
- Supports both images and videos as carousel cards.
- Meta supports 2-10 cards per carousel.
- Include page and insta for Meta launches.

### Launch Flexible Ads
Docs: https://admanage.ai/api-docs/post-launch-flexible
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Meta only. Launch a flexible ad (Advantage+ Creative) where Meta dynamically selects which media and text combinations to show for best performance.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Flexible - Spring Sale",
      "adAccountId": "act_123456789",
      "type": "flexible",
      "title": "Spring Sale",
      "description": "Shop our collection",
      "adDescription": "Limited time offer",
      "cta": "SHOP_NOW",
      "link": "https://example.com",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "headlineVariations": [
        "Spring Sale",
        "Fresh arrivals",
        "Trending now"
      ],
      "bodyVariations": [
        "Shop our collection",
        "New season, new offers",
        "Meta will test the best combination"
      ],
      "adSets": [
        {
          "value": "120012345678901234",
          "label": "US Broad 25-44"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/flexible-1.jpg"
        },
        {
          "url": "https://media.admanage.ai/admanage.ai/flexible-2.mp4"
        }
      ]
    }
  ]
}
```

Notes:
- This ad type is Meta (Facebook/Instagram) only.
- Set type to "flexible" for Advantage+ Creative / flexible ads.
- Meta automatically tests combinations of your media and text.
- Provide 1+ media items. Multiple items give Meta more combinations to test.
- headlineVariations and bodyVariations are optional. If omitted, Meta falls back to the top-level title and description.
- Supports both images and videos.
- Include page and insta for Meta launches.

### Launch Ads From Draft
Docs: https://admanage.ai/api-docs/post-launch-from-draft
Method: POST
Path: https://api.admanage.ai/v1/launch/from-draft
Category: Launch Meta Ads
Mutating: yes
Re-launch an existing ad batch (draft or previously failed) by its batch ID.

Request body example:
```json
{
  "batchId": 9911
}
```

Notes:
- Returns 202 Accepted — the launch is asynchronous.
- The batch must belong to the authenticated company.

### Launch Meta Partnership Code Ads
Docs: https://admanage.ai/api-docs/post-launch-partnership-code
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Meta Ads
Mutating: yes
Meta only. Launch a branded-content / partnership ad straight from a creator-shared partnership ad code (e.g. 'adcode-...'). Set partnershipCode on the ad — the creator's existing post is used, so media[] can be empty. For the creator-ID based partnership flow, use the partnershipAd object instead.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Creator Collab - Partnership Code",
      "adAccountId": "act_384730851257635",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "partnershipCode": "adcode-abc123def456",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "page": "470703006115773",
      "insta": "17841471826052348",
      "adSets": [
        {
          "value": "120249198609970456",
          "label": "US Broad 25-44"
        }
      ]
    }
  ]
}
```

Notes:
- Meta (Facebook/Instagram) only.
- Set partnershipCode to the partnership ad code the creator shared (starts with 'adcode-' or a 16+ character code).
- media[] can be omitted — the ad runs from the creator's existing post referenced by the code.
- Still pass page and insta — the launcher uses them as the brand identity.
- The row type is auto-set to 'partnershipCode' when partnershipCode is provided and no explicit type is set.
- For the creator-ID based partnership flow (numeric creatorId / creatorPageId), use the partnershipAd object instead.
- Poll GET /v1/batch-status/{adBatchId} to track progress.

### Check Batch Status
Docs: https://admanage.ai/api-docs/check-batch-status
Method: GET
Path: https://api.admanage.ai/v1/batch-status/{id}
Category: Launch Meta Ads
Mutating: no
Lightweight status polling endpoint for launch progress. Poll this after launching until status is "success" or "error".

Notes:
- Poll this endpoint after POST /v1/launch to track progress.
- Use `summaryStatus` for the simple lifecycle: "in_progress", "success", or "error".
- `status` and `rawStatus` are preserved for compatibility with existing polling clients.
- When status is "processing", progress shows percentage complete.
- When status is "success", all ads have been launched.

### Launch TikTok Ads
Docs: https://admanage.ai/api-docs/post-launch-tiktok
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch TikTok Ads
Mutating: yes
Launch TikTok ads via the API. Set adAccountType to 'tiktok'. The launcher auto-resolves TikTok identity (tikSelectedProfile) and enriches ad sets with Smart+ campaign type. Videos are uploaded to TikTok automatically from any URL.

Request body example:
```json
{
  "ads": [
    {
      "adName": "TikTok API Ad",
      "adAccountId": "7486153503963054097",
      "adAccountType": "tiktok",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "Try it today",
      "description": "Launch ads faster with AdManage",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "adSets": [
        {
          "value": "1859479128199217",
          "label": "testgroup manual sales"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
        }
      ]
    }
  ]
}
```

Notes:
- Set adAccountType to 'tiktok' — the launcher auto-detects Smart+ vs manual campaigns.
- TikTok identity (tikSelectedProfile) is auto-resolved from the TikTok API if not provided.
- Videos are uploaded to TikTok from any URL (media.admanage.ai, Google Drive, Dropbox, etc.).
- Smart+ (UPGRADED_SMART_PLUS) campaigns are fully supported — videos are combined automatically.
- Catalog ad groups may reject certain CTAs (LEARN_MORE). Use SHOP_NOW for catalog campaigns.
- Poll GET /v1/batch-status/{adBatchId} to track progress.

### Launch TikTok Spark Ads
Docs: https://admanage.ai/api-docs/post-launch-tiktok-spark
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch TikTok Ads
Mutating: yes
Launch a TikTok Spark Ad straight from a creator-shared Spark Ads auth code (spark code). Set sparkCode on the ad — the creator's organic post, identity, and tiktok_item_id are resolved server-side from the code, so media[] can be empty and no selectedTikTokUserAccount is needed.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Creator Spark - Organic Post",
      "adAccountId": "7486153503963054097",
      "adAccountType": "tiktok",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "sparkCode": "TTAUTHCODE_abc123def456",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "adSets": [
        {
          "value": "1859479128199217",
          "label": "testgroup manual sales"
        }
      ]
    }
  ]
}
```

Notes:
- Set adAccountType to 'tiktok' and sparkCode to the auth code the creator shared.
- media[] can be omitted — the ad runs from the creator's organic post referenced by the code.
- Identity and tiktok_item_id are resolved server-side from the code; selectedTikTokUserAccount is not needed.
- The row stays type 'single' — the TikTok launcher detects sparkCode and routes it to the Spark Ad path.
- Works for both video and photo (carousel) organic posts.
- Poll GET /v1/batch-status/{adBatchId} to track progress.

### Query TikTok Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-tiktok-reports-query-channel
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Launch TikTok Ads
Mutating: no
Return TikTok ad, ad group, or campaign performance for connected TikTok advertiser accounts. This duplicates the Reports section so TikTok users can find metric sync examples in the TikTok section.

Query example:
accountIds=7486153503963054097&startDate=2026-05-19&endDate=2026-05-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=25

Notes:
- Use the TikTok advertiser ID as accountIds.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
- The same endpoint is also documented in Reports as Query TikTok Ad Account Metrics.

### Launch Snapchat Ads
Docs: https://admanage.ai/api-docs/post-launch-snapchat
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Snapchat Ads
Mutating: yes
Launch Snapchat ads via the API. `snapchatProfileId` is required, `snapchatBrandName` is optional, and the platform supports WEB_VIEW, APP_INSTALL, SNAP_AD, COLLECTION, DEEP_LINK, and STORY launches.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Snapchat Story API Ad",
      "adAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
      "adAccountType": "snapchat",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "Tap into the drop",
      "description": "Swipe up to shop the new release.",
      "cta": "SHOP_NOW",
      "link": "https://admanage.ai/",
      "snapchatProfileId": "f7d4c656-25a5-4884-af6a-d9ee9721f920",
      "snapchatAdType": "STORY",
      "snapchatStoryChildAdType": "WEB_VIEW",
      "snapchatStoryPreviewHeadline": "Shop The Latest Drop",
      "snapchatStoryPreviewUrl": "https://media.admanage.ai/admanage.ai/1775585047722-c4d8bca8-988a-4ae8-a4c8-2a8084af9a65.jpeg",
      "snapchatHeadline": "Tap into the drop",
      "snapchatCTA": "SHOP_NOW",
      "adSets": [
        {
          "value": "47c07634-20be-4a4b-99a0-ea98e1bd12a0",
          "label": "Landing Page Views"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
        },
        {
          "url": "https://media.admanage.ai/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
        }
      ]
    }
  ]
}
```

Notes:
- Required on every Snapchat ad: `snapchatProfileId` and at least one Snapchat ad squad in `adSets`. `snapchatBrandName` is optional, and `snapchatProfile` is optional helper metadata.
- Supported `snapchatAdType` values: `WEB_VIEW` (default), `APP_INSTALL`, `SNAP_AD`, `COLLECTION`, `DEEP_LINK`, and `STORY`.
- `WEB_VIEW` and `SNAP_AD` require a landing page `link`. `APP_INSTALL` and `DEEP_LINK` require app IDs plus `snapchatIconMediaId` or `snapchatIconUrl`. `DEEP_LINK` also requires `snapchatDeepLinkUri`.
- `STORY` requires `snapchatStoryChildAdType`, `snapchatStoryPreviewHeadline`, and either `snapchatStoryPreviewMediaId` or `snapchatStoryPreviewUrl`, plus 1-20 `media` items ordered as Story cards.
- Story cards can be images or videos. The quickstart example uses image cards because they are the simplest path to a valid Story launch.
- To launch from scratch, first create a Snapchat campaign and ad squad: `POST /v1/manage/snapchat/create-campaign` then `POST /v1/manage/snapchat/create-adsquad`.
- `snapchatCTA`: `MORE`, `INSTALL_NOW`, `WATCH`, `VIEW`, `APPLY_NOW`, `SHOP_NOW`, etc.
- Ad squad IDs use UUID format (e.g., '47c07634-20be-4a4b-99a0-ea98e1bd12a0').
- Supports both images and videos. Single-image launches are auto-resized to 1080x1920 where possible.
- Poll `GET /v1/batch-status/{adBatchId}` to track progress after the launch request returns.

### Launch Pinterest Ads
Docs: https://admanage.ai/api-docs/post-launch-pinterest
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Pinterest Ads
Mutating: yes
Launch Pinterest ads via the API. Board ID is optional — if not provided or not writable, a new board is auto-created. Supports both image and video pins.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Pinterest API Ad",
      "adAccountId": "549769890977",
      "adAccountType": "pinterest",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "Pin title",
      "description": "Pin description",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "pinterestBoardId": "879820545894149277",
      "adSets": [
        {
          "value": "2680088752234",
          "label": "Ad group copy"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/234234ad_932200713WBIit8kT.jpg"
        }
      ]
    }
  ]
}
```

Notes:
- pinterestBoardId is optional. If not provided or not writable, a new board is auto-created under your Pinterest account.
- Supports both image URLs (.jpg, .png) and video URLs (.mp4). Images launch much faster.
- pinterestCTA: 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', etc.
- CATALOG_SALES campaign objectives use 'SHOPPING' creative type automatically.

### Query Pinterest Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-pinterest-reports-query-channel
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Launch Pinterest Ads
Mutating: no
Return Pinterest ad, ad group, or campaign performance for connected Pinterest ad accounts. This duplicates the Reports section so Pinterest users can find metric sync examples in the Pinterest section.

Query example:
accountIds=549769890977&startDate=2026-05-19&endDate=2026-05-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=25

Notes:
- Use the Pinterest ad account ID as accountIds.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
- Pass workspaceId when the Pinterest connection is workspace-specific.
- The same endpoint is also documented in Reports as Query Pinterest Ad Account Metrics.

### Launch Axon/AppLovin Ads
Docs: https://admanage.ai/api-docs/post-launch-axon
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Axon Ads
Mutating: yes
Launch Axon (AppLovin) ads via the API. Pass campaigns as adSets (they are converted to axonSelectedCampaigns). Requires end cards (axonEndCards) and 9:16 video.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Axon API Ad",
      "adAccountId": "950967007",
      "adAccountType": "axon",
      "workspaceId": "cmhrv27io0001s4r4ouftfoly",
      "title": "Axon ad title",
      "description": "Axon ad description",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "axonEndCards": [
        {
          "assetId": "26503831",
          "name": "endcard.jpg",
          "type": "image"
        }
      ],
      "adSets": [
        {
          "value": "1781008",
          "label": "0/day US - ROAS"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
        }
      ]
    }
  ]
}
```

Notes:
- adSets are converted to axonSelectedCampaigns (Axon uses campaigns, not ad sets).
- axonEndCards required: array of { assetId, name, type } objects. Must be pre-uploaded endcard asset IDs.
- Videos must be 9:16 aspect ratio (1080x1920). Videos are auto-detected and conversion is attempted if needed.
- Asset approval on Axon can take 30-60 seconds after upload.
- link is required — this is the creative set landing page URL.

### Launch Taboola Ads
Docs: https://admanage.ai/api-docs/post-launch-taboola
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch Taboola Ads
Mutating: yes
Launch Taboola native ads via the API. Requires taboolaCampaignIds and taboolaCampaignNames (existing campaigns). Supports both video and image items.

Request body example:
```json
{
  "ads": [
    {
      "adName": "Taboola API Ad",
      "adAccountId": "taboolaaccount-cedadmanageai",
      "adAccountType": "taboola",
      "workspaceId": "cmhrv27io0001s4r4ouftfoly",
      "title": "Taboola headline",
      "description": "Taboola description",
      "cta": "LEARN_MORE",
      "link": "http://admanage.ai",
      "taboolaCampaignIds": [
        "48567616"
      ],
      "taboolaCampaignNames": [
        "New Campaign_20260310"
      ],
      "adSets": [],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/234234ad_932200713WBIit8kT.mp4"
        }
      ]
    }
  ]
}
```

Notes:
- taboolaCampaignIds and taboolaCampaignNames are required (arrays). First element is used as the target campaign.
- adSets should be an empty array [] — Taboola uses campaigns, not ad sets.
- Supports video (.mp4) and image URLs. Videos are uploaded via direct upload with fallback thumbnails.
- link is required — the destination URL for the native ad.
- title is the headline shown in the Taboola feed (max ~60 characters for best performance).

### Launch LinkedIn Ads
Docs: https://admanage.ai/api-docs/post-launch-linkedin
Method: POST
Path: https://api.admanage.ai/v1/launch
Category: Launch LinkedIn Ads
Mutating: yes
Launch LinkedIn ads via the shared launch API. Supports single image, video, carousel, and existing-post workflows through LinkedIn-specific fields on each ad object.

Request body example:
```json
{
  "ads": [
    {
      "adName": "LinkedIn Website Visits API Ad",
      "adAccountId": "507667431",
      "adAccountType": "linkedin",
      "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
      "title": "LinkedIn launch headline",
      "description": "Launch LinkedIn creatives and keep campaign workflows in one place.",
      "cta": "LEARN_MORE",
      "link": "https://admanage.ai/",
      "linkedinHeadline": "Scale LinkedIn launches",
      "linkedinDescription": "Keep launch, copy, and reporting workflows in one API surface.",
      "linkedinCTA": "LEARN_MORE",
      "linkedinAdFormat": "SINGLE_IMAGE",
      "linkedinObjective": "WEBSITE_VISITS",
      "adSets": [
        {
          "value": "720480604",
          "label": "Website Visits - US"
        }
      ],
      "media": [
        {
          "url": "https://media.admanage.ai/admanage.ai/linkedin-launch-example.png"
        }
      ]
    }
  ]
}
```

Notes:
- Set `adAccountType` to `linkedin` on each ad row.
- Use LinkedIn campaign IDs in `adSets`. LinkedIn launches target campaigns rather than Meta-style ad sets.
- `linkedinHeadline`, `linkedinDescription`, and `linkedinCTA` override the generic `title`, `description`, and `cta` fields when provided.
- `linkedinAdFormat` supports `SINGLE_IMAGE`, `VIDEO`, and `CAROUSEL`.
- For carousel launches, provide `carouselCards` with per-card headlines and landing URLs.
- For boost-style launches, use `media[].existingPostUrn` from `GET /v1/linkedin/organization-posts`.
- `linkedinObjective` supports `BRAND_AWARENESS`, `ENGAGEMENT`, `VIDEO_VIEWS`, `WEBSITE_VISITS`, `WEBSITE_CONVERSIONS`, `LEAD_GENERATION`, and `JOB_APPLICANTS`.
- Poll `GET /v1/batch-status/{adBatchId}` to track progress after the launch request returns.

### Query Reports
Docs: https://admanage.ai/api-docs/get-reports-query
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Reports
Mutating: no
Query ad performance data for connected Meta/Facebook, Google Ads, TikTok, and Pinterest ad accounts. Uses BigQuery first for Meta and falls back to platform-specific APIs where needed.

Query example:
accountIds=act_123456789&startDate=2026-02-01&endDate=2026-02-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=100&offset=0&filterOperator=AND&adSetIds=23851234567890,23851234567891&campaignIds=23851000000001

Notes:
- Required: accountIds, startDate, endDate, metrics.
- This endpoint is paginated. Increase limit to return more rows per request, up to 100 at a time.
- Use offset to fetch the next page: start with offset=0, then 100, 200, 300, and continue until pagination.hasMore is false.
- Metrics: spend, impressions, clicks, ctr, cpm, cpc, reach, frequency, videoViews, hookRate, purchases, purchaseValue, roas, etc.
- Google Ads supports spend, impressions, clicks, conversions, conversionValue, roas, purchaseRoas, results, cpc, cpm, ctr, conversionRate, and costPerResult.
- Use groupBy=campaignName for campaign tables and groupBy=adsetName for ad set tables.
- Group by: adId (default), adName, campaignName, adsetName, landingPage, assetType, creative, body, title, callToActionType, adStatus, objective.
- adSetIds: comma-separated ad set IDs to filter results to specific ad sets (e.g. adSetIds=23851234567890,23851234567891).
- campaignIds: comma-separated campaign IDs to filter results to specific campaigns (e.g. campaignIds=23851000000001).
- filterOperator: AND (default) or OR — controls how multiple filters combine.
- excludePatterns: comma-separated patterns to strip from ad names when grouping (e.g. '- Copy,- v2').
- filters: JSON-encoded array. Operators: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, IN, NOT_IN, HIGHER_THAN, LOWER_THAN, BETWEEN, NOT_BETWEEN, EMPTY, NOT_EMPTY.
- Account ownership is validated — invalid account IDs are skipped with a warning.
- When data is empty, returns 200 with data: [] and metadata.warnings explaining why (e.g. pipeline not configured, no token found).
- New accounts with no spend data return an empty response with warnings — never a 500.
- Channel coverage: use this for Meta/Facebook, Google Ads, TikTok, and Pinterest. For Snapchat use GET /v1/spend/daily or the /v1/manage/snapchat/* endpoints, and for LinkedIn use GET /v1/linkedin/manage.
- Use GET /v1/reports/fields for full list of available metrics and dimensions.

### Query Meta Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-reports-query-meta
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Reports
Mutating: no
Return ad-level, ad set-level, or campaign-level performance for connected Meta/Facebook ad accounts in the authenticated workspace.

Query example:
accountIds=act_123456789&startDate=2026-02-01&endDate=2026-02-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc,reach,frequency,purchases,purchaseValue&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=100

Notes:
- Use accountIds with Meta ad account IDs, including the act_ prefix.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad set rows, or groupBy=campaignName for campaign rows.
- For country-level Meta reporting, use GET /v1/reports/meta/country-breakdown.
- If BigQuery data is unavailable, AdManage falls back to the Meta Graph API when allowMetaFallback is true.

### Query Google Ads Account Metrics
Docs: https://admanage.ai/api-docs/get-reports-query-google
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Reports
Mutating: no
Return live Google Ads performance rows for connected Google Ads accounts. This is the API to use when you need Google spend, impressions, clicks, conversions, and ROAS in a dashboard.

Query example:
accountIds=7037703309&startDate=2026-02-01&endDate=2026-02-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,purchaseRoas,cpc,cpm,ctr,conversionRate,costPerResult&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=100

Notes:
- Use the Google Ads customer ID as accountIds, without dashes when possible.
- Supported grouping includes groupBy=adId, adName, adsetName, and campaignName.
- If credentials are missing or expired, the response returns data: [] with metadata.warnings explaining that Google Ads must be connected in AdManage settings.
- GET /v1/google-ads/campaigns still exists for cached campaign/ad group structure, but use this reports endpoint for dashboard metric queries.

### Query TikTok Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-reports-query-tiktok
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Reports
Mutating: no
Return TikTok ad performance for connected TikTok advertiser accounts, including spend, impressions, clicks, conversions, and ROAS-style metrics where TikTok returns them.

Query example:
accountIds=7490123456789012345&startDate=2026-02-01&endDate=2026-02-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=100

Notes:
- Use the TikTok advertiser ID as accountIds.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
- TikTok metrics depend on the advertiser's connected token and TikTok's reporting availability for the requested date range.

### Query Pinterest Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-reports-query-pinterest
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Reports
Mutating: no
Return Pinterest ad performance for connected Pinterest ad accounts, including spend, impressions, clicks, conversions, and ROAS-style metrics where Pinterest returns them.

Query example:
accountIds=549755885175&startDate=2026-02-01&endDate=2026-02-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=100

Notes:
- Use the Pinterest ad account ID as accountIds.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
- Pinterest values depend on the connected Pinterest token and the date range supported by Pinterest analytics.

### Get Report Fields
Docs: https://admanage.ai/api-docs/get-reports-fields
Method: GET
Path: https://api.admanage.ai/v1/reports/fields
Category: Reports
Mutating: no
Returns available dimensions and metrics for building GET /v1/reports/query requests. These fields apply to the shared Meta/Facebook, TikTok, and Pinterest reporting endpoint.

### Get Meta Reach Composition
Docs: https://admanage.ai/api-docs/get-meta-reach-composition
Method: GET
Path: https://api.admanage.ai/v1/reports/meta/reach-composition
Category: Reports
Mutating: no
Return monthly Meta reach composition for one ad account, including cumulative reach and incremental reach (same as net-new reach). Mirrors the core calculations used in the AdManage reach report.

Query example:
accountId=act_123456789&startDate=2025-01-01&endDate=2025-03-31&campaignIds=12020001,12020002&countries=US,CA

Notes:
- Required: accountId, startDate, endDate.
- Meta only. Pass one Meta ad account ID per request.
- incrementalReach is an alias of netNewReach.
- campaignIds and countries are optional comma-separated filters.
- When campaign filters are applied, cumulative reach is rebased so the filtered series starts at a zero baseline.
- If access is missing or expired, the endpoint returns empty data with details in metadata.warnings and may include metadata.requiresReauth=true.

### Get Meta Country Breakdown
Docs: https://admanage.ai/api-docs/get-meta-country-breakdown
Method: GET
Path: https://api.admanage.ai/v1/reports/meta/country-breakdown
Category: Reports
Mutating: no
Return Meta spend, impressions, clicks, and conversion actions broken down by country for one ad account. Use this when you need country-level spend (e.g. UK-only) — the standard /v1/reports/query endpoint does not expose a country dimension. Also returns per-campaign × country rows.

Query example:
accountId=act_123456789&startDate=2026-01-01&endDate=2026-01-31&campaignIds=12020001,12020002&countries=US,GB

Notes:
- Required: accountId, startDate, endDate.
- Meta only. Pass one Meta ad account ID per request.
- countries and campaignIds are optional comma-separated filters. Country codes are ISO-2 (e.g. US, GB, CA).
- Data is aggregated by country for the full period — the endpoint does not return a daily breakdown.
- If access is missing or expired, the endpoint returns empty data with details in metadata.warnings and may include metadata.requiresReauth=true.

### Create Launch Draft
Docs: https://admanage.ai/api-docs/create-draft
Method: POST
Path: https://api.admanage.ai/v1/drafts
Category: Drafts
Mutating: yes
Save a new launch draft with creative state for later iteration and launching.

Request body example:
```json
{
  "title": "My Draft",
  "businessId": "act_123456789",
  "state": {
    "globalDefaults": {
      "title": "Spring Sale",
      "description": "Shop our collection",
      "businessId": "act_123456789",
      "adAccountType": "facebook",
      "launchMode": "gallery",
      "selectedAdSets": []
    },
    "rows": [
      {
        "id": "row-1",
        "adName": "Creative 1",
        "title": "Spring Sale",
        "description": "Shop our collection",
        "cta": "LEARN_MORE",
        "link": "https://example.com",
        "selectedAdSets": [],
        "videos": [
          {
            "name": "creative-1.jpg",
            "type": "image",
            "preview": "https://example.com/creative-1.jpg"
          }
        ]
      }
    ]
  }
}
```

Notes:
- Returns 201 Created.
- businessId is required.
- workspaceId is optional. Omit it unless you need a specific workspace ID.
- state holds the full creativeState (globalDefaults + rows).
- In the docs runner, signed-in users auto-fill the default ad account and workspace where available.

### List Launch Drafts
Docs: https://admanage.ai/api-docs/list-drafts
Method: GET
Path: https://api.admanage.ai/v1/drafts
Category: Drafts
Mutating: no
Paginated list of launch drafts. Does not include the state field (large JSON) — use GET /v1/drafts/:id to load full state.

Query example:
page=1&limit=25&businessId=act_123456789

Notes:
- Filters: businessId, workspaceId, search.
- state is omitted from list results for performance.

### Get Launch Draft By ID
Docs: https://admanage.ai/api-docs/get-draft-by-id
Method: GET
Path: https://api.admanage.ai/v1/drafts/{id}
Category: Drafts
Mutating: no
Fetch a single launch draft including the full state (creativeState JSON).

### Update Launch Draft
Docs: https://admanage.ai/api-docs/update-draft
Method: PATCH
Path: https://api.admanage.ai/v1/drafts/{id}
Category: Drafts
Mutating: yes
Partial update of a launch draft. Update title, state, status, businessId, or workspaceId.

Request body example:
```json
{
  "title": "Updated Draft",
  "state": {
    "globalDefaults": {
      "title": "Summer Sale"
    },
    "rows": [
      {
        "id": "row-1",
        "adName": "Updated Creative"
      }
    ]
  }
}
```

Notes:
- All fields are optional — only provided fields are updated.

### Delete Launch Draft
Docs: https://admanage.ai/api-docs/delete-draft
Method: DELETE
Path: https://api.admanage.ai/v1/drafts/{id}
Category: Drafts
Mutating: yes
Delete a launch draft. Company-scoped — only drafts belonging to your company can be deleted.

### Launch Draft
Docs: https://admanage.ai/api-docs/launch-draft
Method: POST
Path: https://api.admanage.ai/v1/drafts/{id}/launch
Category: Drafts
Mutating: yes
Launch a saved draft. Loads the draft state, creates an ad batch, dispatches to launcher, and marks the draft as 'launched'.

Notes:
- Returns 202 Accepted — the launch is asynchronous.
- Poll GET /v1/batch-status/{adBatchId} to track progress.
- Draft status is updated to 'launched' on success.

### Upload Media
Docs: https://admanage.ai/api-docs/upload-media
Method: POST
Path: https://api.admanage.ai/v1/media/upload
Category: Uploading Media
Mutating: yes
Upload a media file using multipart/form-data. The file stream is proxied to upload-api.

Request body example:
```json
{
  "file": "<binary-file>"
}
```

Notes:
- Use multipart/form-data with field name 'file'.
- For URL-based uploads, use POST /v1/media/upload/url.
- The id/adid fields are numbers (not strings). You do NOT need to pass these IDs back when launching — just use the returned url in your media array.
- To launch with an uploaded file: { media: [{ url: "<returned url>" }] }. Type (video/image) is auto-detected from the filename extension.

### Upload Media From URL
Docs: https://admanage.ai/api-docs/upload-media-from-url
Method: POST
Path: https://api.admanage.ai/v1/media/upload/url
Category: Uploading Media
Mutating: yes
Upload media by providing a public URL. The file is downloaded and stored on AdManage's CDN. Use the returned url in your launch request.

Request body example:
```json
{
  "url": "https://cdn.example.com/creative.mp4"
}
```

Notes:
- The id/adid fields are numbers (not strings). You do NOT need to pass these back — just use the returned url.
- To launch with this media: { media: [{ url: "<returned url>" }] }.

### Check Media Filename
Docs: https://admanage.ai/api-docs/check-media-duplicate
Method: POST
Path: https://api.admanage.ai/v1/media/upload/check
Category: Uploading Media
Mutating: no
Check whether a filename already exists before upload.

Request body example:
```json
{
  "fileName": "summer-ugc-v1.mp4"
}
```

### Search Stored Media
Docs: https://admanage.ai/api-docs/search-connect-media
Method: GET
Path: https://api.admanage.ai/v1/media/search
Category: Uploading Media
Mutating: no
List and filter stored media creatives by query, tags, type, status, and dimensions with paginated results.

Query example:
q=summer&type=video&tags=ugc,hook&page=1&limit=25

Notes:
- Supported query params: q, tags (comma-separated), status, type (image|video), dimension, page, limit.
- Only returns media records that already have an adid.

### Get Stored Media By ID
Docs: https://admanage.ai/api-docs/get-connect-media
Method: GET
Path: https://api.admanage.ai/v1/media/{id}
Category: Uploading Media
Mutating: no
Retrieve a single stored media creative by numeric adid.

Notes:
- id in path is the media adid (number).

### Get Upload URL
Docs: https://admanage.ai/api-docs/get-upload-url
Method: POST
Path: https://api.admanage.ai/v1/media/get-upload-url
Category: Uploading Media
Mutating: no
Get a presigned URL for direct media file upload. The URL expires in 1 hour. Upload the file via multipart POST to the returned URL, then call confirm-upload to register it.

Request body example:
```json
{
  "fileName": "creative-hero.mp4"
}
```

Notes:
- fileName (required): original filename with extension.
- Upload flow: get-upload-url → upload file to URL → confirm-upload.
- The presigned URL expires in 1 hour.

### Confirm Upload
Docs: https://admanage.ai/api-docs/confirm-upload
Method: POST
Path: https://api.admanage.ai/v1/media/confirm-upload
Category: Uploading Media
Mutating: yes
Register an uploaded file in the media library after uploading via the presigned URL. Returns the new asset with metadata.

Request body example:
```json
{
  "url": "https://media.admanage.ai/uploads/abc123/creative-hero.mp4",
  "fileName": "creative-hero.mp4"
}
```

Notes:
- url (required): the media.admanage.ai URL after upload.
- fileName (optional): original filename for display.

### Generate Thumbnail
Docs: https://admanage.ai/api-docs/generate-thumbnail
Method: POST
Path: https://api.admanage.ai/v1/media/generate-thumbnail
Category: Uploading Media
Mutating: yes
Generate a thumbnail for a video file. Non-blocking — can be called after confirm-upload.

Request body example:
```json
{
  "url": "https://media.admanage.ai/uploads/abc123/creative-hero.mp4"
}
```

Notes:
- url (required): media.admanage.ai video URL.
- Non-video files return a skip message.

### List Library Assets
Docs: https://admanage.ai/api-docs/list-library-assets
Method: GET
Path: https://api.admanage.ai/v1/library/assets
Category: Library
Mutating: no
Search and filter creative assets in the media library with cursor-based pagination.

Query example:
limit=25&filterType=video&sortBy=dateCreated&sortOrder=desc&search=ugc

Notes:
- Cursor-based pagination (limit + cursor). Max 100 per page.
- filterType: all, image, video, gif.
- sortBy: dateCreated, dateModified, name, size.
- launchChannels: comma-separated (meta, tiktok, snapchat, pinterest, axon).
- dimension: exact (1080x1920) or aspect ratio (9:16).

### Get Library Asset
Docs: https://admanage.ai/api-docs/get-library-asset
Method: GET
Path: https://api.admanage.ai/v1/library/assets/{id}
Category: Library
Mutating: no
Fetch a single asset by ID with full details including transcript, comments, and launch channels.

Notes:
- Looks up by both internal id and external adid.

### List Library Boards
Docs: https://admanage.ai/api-docs/list-library-boards
Method: GET
Path: https://api.admanage.ai/v1/library/boards
Category: Library
Mutating: no
List boards as a hierarchical tree with asset counts. Team boards are visible to all; private boards only to their creator.

### List Board Assets
Docs: https://admanage.ai/api-docs/list-library-board-assets
Method: GET
Path: https://api.admanage.ai/v1/library/boards/{id}/assets
Category: Library
Mutating: no
List assets in a specific board. Same filters and response shape as GET /v1/library/assets.

Query example:
limit=25&sortBy=dateCreated

Notes:
- Returns 404 if board does not exist or does not belong to the company.

### List Library Tags
Docs: https://admanage.ai/api-docs/list-library-tags
Method: GET
Path: https://api.admanage.ai/v1/library/tags
Category: Library
Mutating: no
List all tags in the media library for the authenticated company.

### Query Meta Ad Account Metrics
Docs: https://admanage.ai/api-docs/get-meta-reports-query-channel
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Manage Meta Ads
Mutating: no
Return Meta/Facebook ad, ad set, or campaign performance for connected Meta ad accounts. This duplicates the Reports section so Meta users can find metric sync examples in the Meta section.

Query example:
accountIds=act_3863802906447&startDate=2026-05-05&endDate=2026-05-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc,reach,frequency&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=25

Notes:
- Use accountIds with Meta ad account IDs, including the act_ prefix.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad set rows, or groupBy=campaignName for campaign rows.
- For country-level Meta reporting, use GET /v1/reports/meta/country-breakdown.
- The same endpoint is also documented in Reports as Query Meta Ad Account Metrics.

### Create Meta Campaign
Docs: https://admanage.ai/api-docs/create-campaign
Method: POST
Path: https://api.admanage.ai/v1/manage/create-campaign
Category: Manage Meta Ads
Mutating: yes
Create a Meta campaign from scratch. Supports core campaign setup plus the advanced budgeting, bidding, promoted-object, and Advantage+/SKAN fields used by the /manage flow.

Request body example:
```json
{
  "businessId": "act_384730851257635",
  "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
  "name": "API Docs - Prospecting Campaign",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "buyingType": "AUCTION",
  "specialAdCategories": [],
  "dailyBudget": 100,
  "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
  "campaignSpendCap": 5000,
  "isAdvantagePlusCampaign": false,
  "promotedObject": {
    "pixel_id": "123456789012345"
  }
}
```

Notes:
- Required: `businessId` (Meta ad account), `name`, and `objective`.
- Budgeting: send `dailyBudget` or `lifetimeBudget` in account currency. Campaign budgets are converted to Meta minor units automatically.
- Supported objectives include `OUTCOME_TRAFFIC`, `OUTCOME_ENGAGEMENT`, `OUTCOME_LEADS`, `OUTCOME_AWARENESS`, `OUTCOME_SALES`, and `OUTCOME_APP_PROMOTION`.
- For `OUTCOME_SALES`, destination choice happens on the ad set, not the campaign. Campaign-level sales examples mainly differ between standard sales campaigns and catalog-bound Advantage+ sales campaigns.
- Advanced options accepted by the public API include `buyingType`, `specialAdCategories`, `bidStrategy`, `campaignBidAmount`, `campaignSpendCap`, `campaignBudgetOptimization`, `campaignBudgetType`, `isAdvantagePlusCampaign`, and `isSkadnetworkAttribution`.
- Use `promotedObject` for conversion/app workflows, for example `{ pixel_id, custom_event_type }` on sales campaigns or `{ application_id, object_store_url }` on app-promotion campaigns.
- The API accepts both camelCase and common Meta snake_case aliases for advanced create payloads.
- Typical workflow: create the campaign first, then create one or more ad sets with `POST /v1/manage/create-adset`, then launch creatives with `POST /v1/launch`.

### Create Meta Ad Set
Docs: https://admanage.ai/api-docs/create-adset
Method: POST
Path: https://api.admanage.ai/v1/manage/create-adset
Category: Manage Meta Ads
Mutating: yes
Create a Meta ad set from scratch under an existing campaign. Supports destination setup, promoted objects, bidding, attribution, Advantage Audience retries, and optional post-create budget schedules.

Request body example:
```json
{
  "businessId": "act_384730851257635",
  "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
  "campaignId": "120251616228380456",
  "name": "API Docs - Traffic Ad Set",
  "status": "PAUSED",
  "dailyBudget": 25,
  "billingEvent": "IMPRESSIONS",
  "optimizationGoal": "LANDING_PAGE_VIEWS",
  "destinationType": "WEBSITE",
  "targeting": {
    "geo_locations": {
      "countries": [
        "US"
      ]
    },
    "age_min": 21,
    "age_max": 55,
    "publisher_platforms": [
      "facebook",
      "instagram"
    ]
  },
  "promotedObject": {
    "pixel_id": "123456789012345"
  },
  "attributionSpec": [
    {
      "event_type": "CLICK_THROUGH",
      "window_days": 7
    }
  ]
}
```

Notes:
- Required: `businessId`, `campaignId`, and `name`.
- Budgeting: send `dailyBudget` or `lifetimeBudget` in account currency. Lifetime budgets require `endTime`.
- Destination and optimization settings follow campaign objective rules. If `optimizationGoal` is omitted, the API infers a Meta-compatible default from the parent campaign objective.
- Sales ad sets commonly use `destinationType` values such as `WEBSITE`, `WEBSITE_AND_PHONE_CALL`, `MESSAGING_INSTAGRAM_DIRECT_MESSENGER`, `MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP`, and `PHONE_CALL`.
- Supported advanced fields include `billingEvent`, `bidStrategy`, `bidAmount`, `destinationType`, `promotedObject`, `attributionSpec`, `startTime`, `endTime`, `pacingType`, `existingCustomerBudgetPercentage`, `placementSoftOptOut`, `targeting`, `dsaBeneficiary`, `dsaPayor`, `valueRuleSetId`, `valueRulesApplied`, `dailyMinSpendTarget`, `dailySpendCap`, `lifetimeMinSpendTarget`, and `lifetimeSpendCap`.
- If Meta rejects the request because Advantage Audience targeting automation is missing or incompatible, the API retries with the same fallback logic used in `/manage`.
- Budget schedules are supported via `budgetSchedules`/`budget_schedules` and are applied after the ad set is created.
- Lead-generation ad sets generally need a lead-gen compatible campaign objective and promoted object. Messenger/DM destinations should use the matching destination/optimization combination.
- The API accepts both camelCase and common Meta snake_case aliases for advanced create payloads.

### Duplicate Ad Set
Docs: https://admanage.ai/api-docs/duplicate-adset
Method: POST
Path: https://api.admanage.ai/v1/manage/duplicate-adset
Category: Manage Meta Ads
Mutating: yes
Duplicate a Facebook ad set (1-10 copies). Uses smartCopy with async batch fallback for large ad sets.

Request body example:
```json
{
  "adsetId": "120248289622780456",
  "accountId": "act_123456789",
  "copyCount": 2,
  "initialStatus": "PAUSED",
  "deepCopy": true,
  "newName": "My Ad Set Copy",
  "workspaceId": "workspace_abc"
}
```

Notes:
- copyCount must be 1-10.
- deepCopy (default true): also copies all ads within the ad set.
- targetCampaignId: optional, duplicates into a different campaign.
- newName: optional, renames the duplicated ad set(s). Response includes renamed (bool) and newName per copy.
- Errors include Facebook error codes/subcodes for debugging. Common errors:
- - Instagram Explore placement: must be selected alongside Explore Home (Facebook validation).
- - Error 1885194: ad set too large for sync copy — the API automatically retries with async batch.
- - Error 2446173: asset label issues — retried without ads attached.
- - Transient errors (code 2) are automatically retried up to 3 times with backoff.

### Create Snapchat Campaign
Docs: https://admanage.ai/api-docs/create-snapchat-campaign
Method: POST
Path: https://api.admanage.ai/v1/manage/snapchat/create-campaign
Category: Manage Snapchat Ads
Mutating: yes
Create a Snapchat campaign before launching ads. Supports objective, budget caps, `objective_v2_properties`, and `measurement_spec` pass-through for app and Story setups.

Request body example:
```json
{
  "businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
  "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
  "name": "Snap Story Campaign",
  "status": "PAUSED",
  "objective": "PROMOTE_STORIES",
  "startTime": "2026-04-11T09:00:00.000Z",
  "dailyBudgetMicro": 25000000
}
```

Notes:
- `businessId` is the Snapchat ad account ID.
- `workspaceId` is optional but recommended when your company has multiple connected Snapchat workspaces.
- If omitted, `status` defaults to `PAUSED`, `objective` defaults to `BRAND_AWARENESS`, `buyModel` defaults to `AUCTION`, and `startTime` defaults to the current time.
- Use `measurementSpec` for app-based campaigns, especially `APP_INSTALL`, `APP_CONVERSION`, and Story flows that swipe to app installs or deep links.
- Advanced fields pass through directly when provided: `objectiveV2Properties`, `regulations`, `mobileAppProperties`, and `sharedProperties`.
- Create an ad squad next with `POST /v1/manage/snapchat/create-adsquad`, then launch creatives with `POST /v1/launch`.

### Create Snapchat Ad Squad
Docs: https://admanage.ai/api-docs/create-snapchat-adsquad
Method: POST
Path: https://api.admanage.ai/v1/manage/snapchat/create-adsquad
Category: Manage Snapchat Ads
Mutating: yes
Create a Snapchat ad squad under an existing campaign. The API can default targeting to US broad and placement to automatic, so you can provision launch-ready ad squads directly from the API.

Request body example:
```json
{
  "businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
  "workspaceId": "cmiypwwnf00012m2rhiutlf3f",
  "campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
  "name": "Snap Story Ad Squad",
  "status": "PAUSED",
  "childAdType": "STORY",
  "optimizationGoal": "STORY_OPENS",
  "dailyBudgetMicro": 15000000,
  "bidStrategy": "AUTO_BID",
  "storyAdCreativeType": "WEB_VIEW",
  "targeting": {
    "regulated_content": false,
    "geos": [
      {
        "country_code": "us"
      }
    ]
  }
}
```

Notes:
- Required: `businessId`, `campaignId`, `name`, `optimizationGoal`, and one of `dailyBudgetMicro` or `lifetimeBudgetMicro`.
- `workspaceId` is optional but recommended when your company has multiple connected Snapchat workspaces.
- Defaults: `status=PAUSED`, `type=SNAP_ADS`, `billingEvent=IMPRESSION`, `bidStrategy=AUTO_BID`, `placementV2={ config: "AUTOMATIC" }`, and targeting defaults to US broad 18+ if omitted.
- Set `childAdType` to match the ad type you plan to launch later: `REMOTE_WEBPAGE`, `APP_INSTALL`, `DEEP_LINK`, `STORY`, `SNAP_AD`, `COLLECTION`, etc.
- For `LOWEST_COST_WITH_MAX_BID` and `TARGET_COST`, send `bidMicro`. For `MIN_ROAS`, send `roasValueMicro`.
- Use `storyAdCreativeType` only when configuring Dynamic Story Ads. Standard Story launches can still use `childAdType: STORY` and then `snapchatAdType: STORY` on `/v1/launch`.
- After the ad squad is created, use its UUID in the `adSets` array when calling `POST /v1/launch`.

### List Snapchat Campaigns
Docs: https://admanage.ai/api-docs/get-snapchat-campaigns
Method: GET
Path: https://api.admanage.ai/v1/manage/snapchat/campaigns
Category: Manage Snapchat Ads
Mutating: no
Fetch Snapchat campaigns for one ad account with spend over the last 90 days. This is the public manage/reporting surface behind the Snapchat campaigns table in /manage.

Query example:
businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20

Notes:
- Required: `businessId` (Snapchat ad account UUID).
- Optional pagination: `page` and `pageSize`.
- Spend is computed from Snapchat stats over the last 90 days and returned in USD.
- Use this when you want Snapchat campaign rows rather than the cross-platform spend chart from `GET /v1/spend/daily`.

### List Snapchat Ad Squads
Docs: https://admanage.ai/api-docs/get-snapchat-adsquads
Method: GET
Path: https://api.admanage.ai/v1/manage/snapchat/adsquads
Category: Manage Snapchat Ads
Mutating: no
Fetch Snapchat ad squads for one ad account, optionally filtered to specific campaigns. Ad squads are the Snapchat equivalent of ad sets.

Query example:
businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20&campaignIds=%5B%2246fb184a-d371-49f0-8384-ea533cef217a%22%5D

Notes:
- Required: `businessId` (Snapchat ad account UUID).
- Optional: `campaignIds` as a JSON array string when you want ad squads for only a subset of campaigns.
- Spend is computed from Snapchat stats over the last 90 days.
- Use ad squad IDs from this response in the `adSets` array when calling `POST /v1/launch` for Snapchat.

### List Snapchat Ads
Docs: https://admanage.ai/api-docs/get-snapchat-ads
Method: GET
Path: https://api.admanage.ai/v1/manage/snapchat/ads
Category: Manage Snapchat Ads
Mutating: no
Fetch Snapchat ads for one ad account with spend and creative preview thumbnails. Optionally filter to specific ad squads.

Query example:
businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20&adsquadIds=%5B%227b99bd80-5279-41c1-9d8d-e28875d7e7dd%22%5D

Notes:
- Required: `businessId` (Snapchat ad account UUID).
- Optional: `adsquadIds` as a JSON array string when you want ads for only a subset of ad squads.
- Spend is computed from Snapchat stats over the last 90 days.
- The API resolves creative preview URLs where possible so the response can drive thumbnail-heavy manage views.

### List LinkedIn Ad Accounts
Docs: https://admanage.ai/api-docs/get-linkedin-accounts
Method: GET
Path: https://api.admanage.ai/v1/linkedin/accounts
Category: Manage LinkedIn Ads
Mutating: no
List the connected LinkedIn ad accounts available to the authenticated company, including account status, currency, role, and organization reference.

Notes:
- No query params are required.
- Use the returned `id` as `adAccountId` in the LinkedIn manage and duplicate endpoints.
- Returns only accounts the connected LinkedIn user can access.

### Query LinkedIn Campaign Groups, Campaigns, or Creatives
Docs: https://admanage.ai/api-docs/get-linkedin-manage
Method: GET
Path: https://api.admanage.ai/v1/linkedin/manage
Category: Manage LinkedIn Ads
Mutating: no
Fetch LinkedIn campaign groups, campaigns, or creatives for one ad account. Optional metrics turn this into the public LinkedIn manage/reporting surface for spend, impressions, clicks, CTR, and CPM.

Query example:
adAccountId=507667431&type=campaigns&includeMetrics=1&startDate=2026-03-01&endDate=2026-03-31

Notes:
- Required: `adAccountId`.
- Optional `type`: `campaignGroups`, `campaigns` (default), or `creatives`.
- Set `includeMetrics=1` to attach spend, impressions, clicks, CTR, and CPM from LinkedIn adAnalytics.
- Optional `startDate` and `endDate` default to the last 30 days when metrics are requested.
- When `type=creatives`, pass `campaignId` to limit results to one campaign and `includeThumbnails=1` to resolve creative preview images.
- This endpoint is LinkedIn-specific. Do not use `GET /v1/reports/query` for LinkedIn.

### List LinkedIn Organization Posts
Docs: https://admanage.ai/api-docs/get-linkedin-organization-posts
Method: GET
Path: https://api.admanage.ai/v1/linkedin/organization-posts
Category: Manage LinkedIn Ads
Mutating: no
Fetch recent organic LinkedIn organization posts for one ad account. Use this to find post URNs for boost-style launches or to populate a post picker in the launch flow.

Query example:
adAccountId=507667431&count=25

Notes:
- Required: `adAccountId` (or `businessId`).
- Optional `count` defaults to 50 and is capped at 100.
- Use `posts[].urn` as `media[].existingPostUrn` when launching existing LinkedIn posts through `POST /v1/launch`.

### Duplicate LinkedIn Campaign Group
Docs: https://admanage.ai/api-docs/post-linkedin-duplicate-campaign
Method: POST
Path: https://api.admanage.ai/v1/linkedin/duplicate-campaign
Category: Manage LinkedIn Ads
Mutating: yes
Duplicate a LinkedIn campaign group. This is the LinkedIn equivalent of duplicating a top-level campaign container before launching or editing child campaigns.

Request body example:
```json
{
  "campaignGroupId": "703344221",
  "adAccountId": "507667431",
  "newName": "Q2 Prospecting Copy",
  "isLive": false
}
```

Notes:
- Required: `campaignGroupId`, `adAccountId`, and `newName`.
- Set `isLive=true` to keep the duplicated campaign group active. Otherwise the API creates it and then pauses it.
- The API copies schedule and budget fields from the source campaign group when present.

### Duplicate LinkedIn Campaign
Docs: https://admanage.ai/api-docs/post-linkedin-duplicate-adgroup
Method: POST
Path: https://api.admanage.ai/v1/linkedin/duplicate-adgroup
Category: Manage LinkedIn Ads
Mutating: yes
Duplicate a LinkedIn campaign. In LinkedIn's model this is the equivalent of duplicating an ad set-level entity under a campaign group.

Request body example:
```json
{
  "campaignId": "720480604",
  "adAccountId": "507667431",
  "newName": "Website Visits - US Copy",
  "isLive": false
}
```

Notes:
- Required: `campaignId`, `adAccountId`, and `newName`.
- Set `isLive=true` to create the duplicated campaign as active. Otherwise it is created paused.
- The API copies the source campaign payload, removes LinkedIn read-only fields, and keeps the original objective and campaign group association.

### Duplicate Campaign
Docs: https://admanage.ai/api-docs/duplicate-campaign
Method: POST
Path: https://api.admanage.ai/v1/manage/duplicate-campaign
Category: Manage Meta Ads
Mutating: yes
Duplicate a Facebook campaign (1-10 copies). Uses smartCopy with async batch fallback for large campaigns.

Request body example:
```json
{
  "campaignId": "120247699100220456",
  "accountId": "act_123456789",
  "copyCount": 1,
  "initialStatus": "PAUSED",
  "deepCopy": true,
  "newName": "My Campaign Copy",
  "workspaceId": "workspace_abc"
}
```

Notes:
- copyCount must be 1-10.
- deepCopy (default true): also copies all ad sets and ads within the campaign.
- newName: optional, renames the duplicated campaign(s). Response includes renamed (bool) and newName per copy.

### Duplicate Axon Campaign
Docs: https://admanage.ai/api-docs/axon-duplicate-campaign
Method: POST
Path: https://api.admanage.ai/v1/manage/axon/duplicate-campaign
Category: Manage Axon Ads
Mutating: yes
Duplicate an Axon/AppLovin campaign through the public Axon manage API. Preserves campaign targeting, goals, and app-tracking settings.

Request body example:
```json
{
  "businessId": "1159321785",
  "sourceCampaignId": "1786048",
  "newCampaignName": "Campaign copy via API",
  "status": "PAUSED",
  "startDate": "2026-04-08T19:39:00",
  "workspaceId": "workspace_abc"
}
```

Notes:
- This endpoint duplicates through Axon's public `campaign/create` API, not the dashboard admin action.
- APP campaigns preserve `tracking`, `platform`, `package_name`, and composite banner settings from the source campaign.
- Axon currently rejects low APP create budgets. If the source budget is below Axon's minimum, the API raises the create budget and returns a warning.
- When `status` is `PAUSED`, the API performs a follow-up Axon `campaign/update` call because Axon create can ignore paused state on APP campaigns.

### Duplicate Ad
Docs: https://admanage.ai/api-docs/duplicate-ad
Method: POST
Path: https://api.admanage.ai/v1/manage/duplicate-ad
Category: Manage Meta Ads
Mutating: yes
Duplicate a Facebook ad with optional creative modifications. Falls back to recreation on pixel/lead form errors.

Request body example:
```json
{
  "adId": "120012345678901234",
  "accountId": "act_123456789",
  "targetAdSetId": "120248289622780456",
  "copyCount": 1,
  "initialStatus": "PAUSED",
  "copyValues": {
    "primaryText1": "New primary text",
    "headline1": "New headline",
    "adName": "My Ad Copy"
  },
  "workspaceId": "workspace_abc"
}
```

Notes:
- copyCount must be 1-10.
- copyValues: optional creative modifications (primaryText1-5, headline1-5, url, urlTags, adName).
- On error codes 1634013/3390001, automatically attempts recreation fallback.
- method in results: 'copies' (standard) or 'recreation' (fallback).

### Get Change History
Docs: https://admanage.ai/api-docs/get-changes
Method: GET
Path: https://api.admanage.ai/v1/manage/changes
Category: Manage Meta Ads
Mutating: no
Fetch Meta activity history for an ad account. Returns changes to campaigns, ad sets, and ads — including budget, bid cap, status, and targeting modifications with old/new values and timestamps.

Query example:
businessId=act_123456789&objectId=120247699100220456&since=1710000000&until=1710300000&workspaceId=workspace_abc&limit=50

Notes:
- businessId (required): the ad account ID (e.g. act_123456789).
- objectId (optional): filter to a specific campaign, ad set, or ad ID.
- since / until (optional): Unix timestamps to define a date range.
- limit: 1-100, default 50.
- Budget values are in minor units (cents). Divide by 100 for the display amount.
- Changes include: budget, bid cap, cost cap, status, targeting, schedule, and more.

### List Ads in Ad Set
Docs: https://admanage.ai/api-docs/list-ads
Method: GET
Path: https://api.admanage.ai/v1/manage/list-ads
Category: Manage Meta Ads
Mutating: no
List ads in a Facebook ad set or ad account directly from the Graph API. Returns ad ID, name, status, effective status, created time, and thumbnail URL. Use this to see which ads exist before deleting, editing, or making room for new launches.

Query example:
adSetId=120248289622780456&limit=50&workspaceId=workspace_abc

Notes:
- Either adSetId or accountId is required. adSetId lists ads in a specific ad set; accountId lists all ads in the account.
- status (optional): filter by effective status — ACTIVE, PAUSED, ARCHIVED, DELETED.
- limit: 1-200, default 50.
- Pair with POST /v1/manage/delete to remove underperforming ads and free up slots before launching new ones.

### Pause, Resume, or End Ads / Ad Sets / Campaigns
Docs: https://admanage.ai/api-docs/update-status
Method: POST
Path: https://api.admanage.ai/v1/manage/update-status
Category: Manage Meta Ads
Mutating: yes
One endpoint for three things: (1) PAUSE — stop delivery immediately. (2) RESUME — re-activate a paused entity. (3) END — schedule when delivery stops via endTime (or end immediately by setting endTime in the past). Works for campaigns, ad sets, and ads on Meta and TikTok. Platform is auto-detected from businessId (act_ = Meta, numeric = TikTok). The entity does NOT need to be synced to AdManage — the ID is passed straight through to the platform's API.

Request body example:
```json
{
  "entityId": "120249137908810789",
  "entityType": "adsets",
  "newStatus": "PAUSED",
  "businessId": "act_384730851257635",
  "workspaceId": "workspace_abc"
}
```

Notes:
- PAUSE immediately: newStatus='PAUSED' (Meta) or 'DISABLE' (TikTok). Omit endTime.
- RESUME a paused entity: newStatus='ACTIVE' (Meta) or 'ENABLE' (TikTok). Omit endTime.
- END on a schedule (Meta only): newStatus='ACTIVE' + endTime (ISO 8601, e.g. '2026-04-22T23:59:59+0000'). Delivery keeps running until endTime, then stops.
- EXTEND or CHANGE an existing end date: call again with a new endTime — it overwrites the previous one.
- entityType: 'campaigns', 'adsets', or 'ads'.
- Meta statuses: 'ACTIVE' or 'PAUSED'. TikTok statuses: 'ENABLE' or 'DISABLE'.
- Platform is auto-detected: act_ prefix = Meta, numeric = TikTok.
- endTime is Meta-only; TikTok ignores it.

### Update Campaign Budget
Docs: https://admanage.ai/api-docs/update-campaign-budget
Method: POST
Path: https://api.admanage.ai/v1/manage/update-campaign-budget
Category: Manage Meta Ads
Mutating: yes
Set the daily or lifetime budget for a Meta campaign. Inputs are dollars; the response includes both dollars and cents. When using lifetimeBudget, provide endTime (ISO 8601).

Request body example:
```json
{
  "campaignId": "120247699100220456",
  "businessId": "act_384730851257635",
  "dailyBudget": 150,
  "workspaceId": "workspace_abc"
}
```

Notes:
- Use campaignId in the request body.
- Provide exactly one of dailyBudget or lifetimeBudget.
- Budget values must be non-negative numbers in account currency dollars, not cents.
- endTime (optional, ISO 8601): required when using lifetimeBudget — Meta needs an end date for lifetime budgets.
- Meta does not allow switching from daily to lifetime budget on an existing entity. Lifetime budget must be set at creation time.
- Response budget.amountDollars is the public API amount. budget.amountCents is the internal Meta minor-unit value used for the mutation.

### Update Ad Set Budget
Docs: https://admanage.ai/api-docs/update-adset-budget
Method: POST
Path: https://api.admanage.ai/v1/manage/update-adset-budget
Category: Manage Meta Ads
Mutating: yes
Set the daily or lifetime budget for a Meta ad set. Inputs are dollars; the response includes both dollars and cents. When using lifetimeBudget, provide endTime (ISO 8601).

Request body example:
```json
{
  "adsetId": "120249483901820456",
  "businessId": "act_384730851257635",
  "dailyBudget": 25,
  "workspaceId": "workspace_abc"
}
```

Notes:
- Use adsetId in the request body.
- Provide exactly one of dailyBudget or lifetimeBudget.
- Budget values must be non-negative numbers in account currency dollars, not cents.
- endTime (optional, ISO 8601): required when using lifetimeBudget — Meta needs an end date for lifetime budgets.
- Meta does not allow switching from daily to lifetime budget on an existing ad set. Lifetime budget must be set at creation time.
- Response budget.amountDollars is the public API amount. budget.amountCents is the internal Meta minor-unit value used for the mutation.

### Update Campaign Bidding
Docs: https://admanage.ai/api-docs/update-campaign-bidding
Method: POST
Path: https://api.admanage.ai/v1/manage/update-campaign-bidding
Category: Manage Meta Ads
Mutating: yes
Update Meta bidding for a campaign. Only supported for AUCTION campaigns using campaign budget optimization (CBO). For capped strategies, AdManage sends Meta the required adset_bid_amounts map for all child ad sets in the campaign update request.

Request body example:
```json
{
  "campaignId": "120247699100220456",
  "businessId": "act_384730851257635",
  "bidStrategy": "LOWEST_COST_WITH_BID_CAP",
  "bidAmount": 35,
  "workspaceId": "workspace_abc"
}
```

Notes:
- Use campaignId in the request body.
- Campaign bidding only applies to AUCTION + CBO campaigns. ABO campaigns must be updated at the ad set level.
- Provide bidStrategy, bidAmount, or both.
- For LOWEST_COST_WITH_BID_CAP, COST_CAP, and TARGET_COST, bidAmount is required unless all child ad sets already have bid_amount values.
- When toggling a CBO campaign from autobid to a capped campaign strategy, Meta requires an adset_bid_amounts map for every non-deleted child ad set.
- bidAmount is in account currency dollars. The response also includes Meta minor units in bidding.bidAmountCents.

### Update Ad Set Bidding
Docs: https://admanage.ai/api-docs/update-adset-bidding
Method: POST
Path: https://api.admanage.ai/v1/manage/update-adset-bidding
Category: Manage Meta Ads
Mutating: yes
Update Meta bidding for an ad set. Supports switching bid_strategy and changing bid_amount for capped strategies.

Request body example:
```json
{
  "adsetId": "120249483901820456",
  "businessId": "act_384730851257635",
  "bidStrategy": "COST_CAP",
  "bidAmount": 12.5,
  "workspaceId": "workspace_abc"
}
```

Notes:
- Use adsetId in the request body.
- Provide bidStrategy, bidAmount, or both.
- For LOWEST_COST_WITH_BID_CAP, COST_CAP, and TARGET_COST, bidAmount is required unless the ad set already has a bid_amount stored on Meta.
- bidAmount is in account currency dollars. The response also includes Meta minor units in bidding.bidAmountCents.

### Update Ad Set ZIP Targeting
Docs: https://admanage.ai/api-docs/update-adset-zip-targeting
Method: POST
Path: https://api.admanage.ai/v1/manage/update-adset-zip-targeting
Category: Manage Meta Ads
Mutating: yes
Merge or replace postal-code targeting on an existing Meta ad set. The endpoint reads the current targeting, adds ZIP keys such as US:43215, removes overlapping country/region/city scopes that Meta rejects, then updates the ad set on Meta.

Request body example:
```json
{
  "adsetId": "120254678681090456",
  "businessId": "act_384730851257635",
  "countryCode": "US",
  "mode": "merge",
  "postalCodes": [
    "43215",
    "55401",
    "20003",
    "94117",
    "78704"
  ],
  "excludedCountries": [
    "CA",
    "MX"
  ],
  "workspaceId": "workspace_abc"
}
```

Notes:
- mode defaults to merge. Use replace to discard existing ZIP keys before adding the submitted postal codes.
- postalCodes and rawText can both be provided; duplicates are removed before calling Meta.
- excludedCountries is optional. Countries that overlap the ZIP country are ignored to avoid Meta's overlapping-locations error.
- Max 200 unique postal codes per request. Send larger lists in batches.
- When ZIPs are applied, AdManage removes country_groups, overlapping countries, regions, cities, and excluded countries for the ZIP country to avoid Meta's overlapping-locations error.
- Every call is written to the activity log as update_adset_zip_targeting. Failed Meta responses include fbError in the logged response body.

### Edit Existing Ads
Docs: https://admanage.ai/api-docs/edit-ads
Method: POST
Path: https://api.admanage.ai/v1/manage/edit-ads
Category: Manage Meta Ads
Mutating: yes
Batch edit existing Facebook ads — change ad name, primary text, headlines, descriptions, URL, CTA, UTM tags, creative enhancements, or schedule.

Request body example:
```json
{
  "accountId": "act_384730851257635",
  "ads": [
    {
      "adId": "120249137908810789",
      "copyValues": {
        "adName": "New Ad Name",
        "primaryText1": "Updated primary text",
        "headline1": "New headline",
        "url": "https://example.com/landing",
        "urlTags": "utm_source=facebook&utm_medium=cpc",
        "cta": "SHOP_NOW"
      }
    }
  ]
}
```

Notes:
- Fast fields (direct update): adName, urlTags, ad_schedule_start_time, ad_schedule_end_time.
- Creative fields (rebuild via launcher): primaryText1-5, headline1-5, description1-5, url, cta, creativeEnhancements.
- creativeEnhancements: 'on' or 'off'.

### List Lead Forms
Docs: https://admanage.ai/api-docs/lead-forms
Method: GET
Path: https://api.admanage.ai/v1/manage/lead-forms
Category: Manage Meta Ads
Mutating: no
List active lead forms for a Facebook Page. Required when launching into a lead gen ad set (objective = OUTCOME_LEADS). Pass the selected form's id as leadFormId in launch.

Query example:
pageId=123456789&workspaceId=workspace_abc

Notes:
- pageId (required): Facebook Page ID from get_launch_defaults or list_profiles.
- Returns only ACTIVE forms, sorted by most recently created.

### Refresh Ad Sets
Docs: https://admanage.ai/api-docs/refresh-adsets
Method: POST
Path: https://api.admanage.ai/v1/manage/refresh-adsets
Category: Manage Meta Ads
Mutating: no
Fetch or refresh ad sets from the Facebook Graph API for an ad account. Supports caching and cooldown to avoid rate limits. In most cases you do NOT need to call this directly — GET /v1/adsets auto-refreshes stale snapshots on read, and ad-set mutations (create, duplicate, update, delete) invalidate the snapshot so the next read refreshes.

Request body example:
```json
{
  "businessId": "act_384730851257635",
  "type": "active",
  "hardRefresh": false,
  "workspaceId": "workspace_abc"
}
```

Notes:
- businessId (required): Facebook ad account ID (act_*).
- type: 'all' (default), 'active', or 'paused'.
- hardRefresh: true to bypass cache. forceRefresh: true to skip cooldown.
- Only Facebook act_* accounts are supported.
- Prefer GET /v1/adsets?refresh=true for ad-hoc live fetches — it auto-refreshes when stale and returns launch-ready rows. Use this endpoint only when you need the raw Meta Graph payload or fine-grained control over the refresh type.

### Duplicate Ad Set (Advanced)
Docs: https://admanage.ai/api-docs/duplicate-adset-advanced
Method: POST
Path: https://api.admanage.ai/v1/manage/duplicate-adset-advanced
Category: Manage Meta Ads
Mutating: yes
Duplicate an ad set with optional targeting updates (locations, custom audiences) and ad duplication. More flexible than the basic duplicate endpoint.

Request body example:
```json
{
  "adsetId": "120248289622780456",
  "accountId": "act_384730851257635",
  "newAdSetName": "US Broad - Copy",
  "duplicateAds": true,
  "duplicateAdsStatus": "PAUSED",
  "isAdSetLive": false,
  "workspaceId": "workspace_abc"
}
```

Notes:
- adsetId (required): source ad set ID.
- duplicateAds: true to copy child ads (default false).
- singleAdId: only duplicate this specific ad from the source.
- locationTargeting, customAudiencesInclude, customAudiencesExclude: override targeting on the copy.

### Update Library Asset
Docs: https://admanage.ai/api-docs/update-library-asset
Method: POST
Path: https://api.admanage.ai/v1/library/assets/{id}/update
Category: Library
Mutating: yes
Update a media asset's metadata — rename, change status, add tags, or set a rating.

Request body example:
```json
{
  "name": "Q1 Hero Video - Final",
  "uploaderStatus": "approved",
  "rating": 5,
  "smartTags": [
    "hero",
    "q1",
    "video"
  ]
}
```

Notes:
- id (path): numeric asset ID from list_library_assets.
- uploaderStatus: 'raw', 'in_progress', 'approved', or 'archived'.
- rating: 1-5.
- All fields are optional — only provided fields are updated.

### Create Library Board
Docs: https://admanage.ai/api-docs/create-library-board
Method: POST
Path: https://api.admanage.ai/v1/library/boards
Category: Library
Mutating: yes
Create a new board (folder) in your creative library to organize media assets. Boards can be nested under a parent board.

Request body example:
```json
{
  "name": "Q1 Creatives",
  "description": "All approved Q1 campaign creatives",
  "visibility": "team"
}
```

Notes:
- name (required): board name.
- parentId (optional): nest under a parent board.
- visibility: 'team' (default, everyone can see) or 'private' (only you).

### Add Asset to Board
Docs: https://admanage.ai/api-docs/add-asset-to-board
Method: POST
Path: https://api.admanage.ai/v1/library/boards/{id}/assets
Category: Library
Mutating: yes
Add a media asset to a board. An asset can belong to multiple boards.

Request body example:
```json
{
  "adId": 12345
}
```

Notes:
- id (path): board ID from list_library_boards.
- adId (body): asset ID from list_library_assets.

### Remove Asset from Board
Docs: https://admanage.ai/api-docs/remove-asset-from-board
Method: DELETE
Path: https://api.admanage.ai/v1/library/boards/{id}/assets
Category: Library
Mutating: yes
Remove a media asset from a board. Only removes the association — the asset itself is not deleted.

Query example:
adId=12345

Notes:
- id (path): board ID.
- adId (query): asset ID to remove.

### Delete Ads / Ad Sets / Campaigns
Docs: https://admanage.ai/api-docs/delete-entities
Method: POST
Path: https://api.admanage.ai/v1/manage/delete
Category: Manage Meta Ads
Mutating: yes
Delete Facebook or Pinterest campaigns, ad sets, or ads (up to 100 at once). Facebook entities are soft-deleted (status set to DELETED). Pinterest entities are archived.

Request body example:
```json
{
  "entityIds": [
    "120249137908810789",
    "120249137908810790"
  ],
  "entityType": "ads",
  "businessId": "act_384730851257635",
  "platform": "facebook",
  "workspaceId": "workspace_abc"
}
```

Notes:
- entityType: 'campaigns', 'adsets', or 'ads'.
- entityIds: array of IDs to delete (max 100).
- businessId: the ad account ID (e.g. act_123 for Meta).
- platform (optional): 'facebook' or 'pinterest'. Auto-detected from businessId if omitted.
- Facebook: sets status to DELETED (soft delete). Pinterest: sets status to ARCHIVED.
- All entity deletions run concurrently (Promise.allSettled). Individual failures don't block other deletions.
- This is destructive and cannot be undone.

### List Automation Rules
Docs: https://admanage.ai/api-docs/list-automations
Method: GET
Path: https://api.admanage.ai/v1/automations
Category: Automations
Mutating: no
Paginated list of automation rules filtered by status, workspace, or search term.

Query example:
page=1&limit=25&status=active&workspaceId=workspace_abc&search=pause

Notes:
- Filters: status, workspaceId, search (name substring).
- Max limit: 100. Default: 25.

### Get Automation Rule
Docs: https://admanage.ai/api-docs/get-automation
Method: GET
Path: https://api.admanage.ai/v1/automations/{id}
Category: Automations
Mutating: no
Fetch a single automation rule with its full flow configuration and 10 most recent executions.

### Create Automation Rule
Docs: https://admanage.ai/api-docs/create-automation
Method: POST
Path: https://api.admanage.ai/v1/automations
Category: Automations
Mutating: yes
Create a new automation rule. For recurring rules (daily/weekly/monthly), the scheduledDate is auto-calculated if not provided.

Request body example:
```json
{
  "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"
}
```

Notes:
- Returns 201 Created.
- Required: name, flow (with nodes array), actionType, accountId.
- frequency: 'one-time' (default), 'daily', 'weekly', 'monthly'.
- For weekly: provide dayOfWeek (e.g. 'monday').
- For monthly: provide dayOfMonth (e.g. '15' or 'last').

### Update Automation Rule
Docs: https://admanage.ai/api-docs/update-automation
Method: PATCH
Path: https://api.admanage.ai/v1/automations/{id}
Category: Automations
Mutating: yes
Partial update of an automation rule. scheduledDate is recalculated when frequency-related fields change.

Request body example:
```json
{
  "status": "paused"
}
```

Notes:
- At least one field must be provided.
- Updatable: name, flow, actionType, accountId, targetId, newName, status, frequency, scheduledDate, scheduledTime, dayOfWeek, dayOfMonth, startDate, endDate, workspaceId.

### Delete Automation Rule
Docs: https://admanage.ai/api-docs/delete-automation
Method: DELETE
Path: https://api.admanage.ai/v1/automations/{id}
Category: Automations
Mutating: yes
Delete an automation rule. Company-scoped — only rules belonging to your company can be deleted.

### Execute Automation Rule
Docs: https://admanage.ai/api-docs/execute-automation
Method: POST
Path: https://api.admanage.ai/v1/automations/{id}/execute
Category: Automations
Mutating: yes
Execute an existing saved automation rule by ID. Returns 202 Accepted with an executionId to poll for status.

Notes:
- Returns 202 Accepted — execution is asynchronous.
- Poll GET /v1/automations/executions/{executionId} for final status.

### Execute Inline Automation
Docs: https://admanage.ai/api-docs/execute-automation-inline
Method: POST
Path: https://api.admanage.ai/v1/automations/execute
Category: Automations
Mutating: yes
Execute an automation flow without saving it as a rule. Useful for one-off or CI-triggered executions.

Request body example:
```json
{
  "flow": {
    "nodes": [
      {
        "id": "action-1",
        "type": "action",
        "data": {}
      }
    ]
  },
  "actionType": "pause_ad",
  "accountId": "act_123456789",
  "dryRun": true
}
```

Notes:
- Returns 202 Accepted — execution is asynchronous.
- Required: flow (with nodes array), actionType, accountId.
- dryRun: true simulates execution without making real changes.

### List Automation Executions
Docs: https://admanage.ai/api-docs/list-automation-executions
Method: GET
Path: https://api.admanage.ai/v1/automations/executions
Category: Automations
Mutating: no
Paginated list of automation execution history. Filterable by status, rule ID, and workspace.

Query example:
page=1&limit=10&status=completed&automationRuleId=1

Notes:
- Filters: status, automationRuleId, workspaceId.
- Status values: running, completed, failed, scheduled_delay, awaiting_approval.

### Get Automation Execution
Docs: https://admanage.ai/api-docs/get-automation-execution
Method: GET
Path: https://api.admanage.ai/v1/automations/executions/{id}
Category: Automations
Mutating: no
Fetch full execution details including stepResults, executionLogs, flow snapshot, and any delayed execution or approval records.

Notes:
- Includes delayedExecution record when status is 'scheduled_delay'.
- Includes approval record when status is 'awaiting_approval'.

### Get Daily Ad Spend
Docs: https://admanage.ai/api-docs/get-daily-spend
Method: GET
Path: https://api.admanage.ai/v1/spend/daily
Category: Spend
Mutating: no
Get daily ad spend per account across all connected platforms (Facebook/Meta, TikTok, Pinterest, Snapchat). Useful for balance management and budget monitoring. Uses BigQuery for Facebook with Graph API fallback. Date range capped at 90 days per request.

Query example:
startDate=2026-03-01&endDate=2026-03-09&accountIds=act_384730851257635&platform=facebook

Notes:
- Use this to recreate the /data/cost daily spend chart in the dashboard.
- Required params: startDate, endDate (YYYY-MM-DD format).
- Optional params: accountIds (comma-separated), workspaceId, platform (facebook, tiktok, pinterest, snapchat).
- This is the only documented public reporting endpoint that spans Meta, TikTok, Pinterest, and Snapchat together.
- Date range is capped at 90 days per request.
- If no accountIds are provided, returns spend for all accounts in your company.
- If a platform fails (e.g. token expired), partial results are returned with an errors array.
- When no matching accounts are found, returns a warnings array explaining why (e.g. invalid account IDs, no accounts connected).
- Spend is returned in each account's native currency.
- BigQuery data is typically one day lagged; today's spend may use the Facebook Graph API fallback.

### Get Comments
Docs: https://admanage.ai/api-docs/get-comments
Method: GET
Path: https://api.admanage.ai/v1/comments
Category: Comments
Mutating: no
List ad comments with filtering and pagination. Comments are collected in real-time from Facebook/Meta via webhooks, with AI-powered sentiment analysis on a 1-100 scale (1-33 negative, 34-66 neutral, 67-100 positive).

Query example:
page=1&limit=25&accountId=act_123456789&sentiment=negative&startDate=2026-03-01&endDate=2026-03-31

Notes:
- Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive.
- Optional: accountId (or adAccountId) to filter by ad account (e.g. act_123).
- Optional: adId to filter by specific ad.
- Optional: sentiment — 'positive', 'neutral', or 'negative'.
- Optional: hidden — 'true' or 'false' to filter by visibility.
- Optional: startDate, endDate (YYYY-MM-DD) for date range.
- Optional: search — case-insensitive search across comment text, author name, or ad name.
- Optional: sortBy — 'commentDate' (default), 'likes', 'sentiment', or 'lastUpdated'.
- Optional: sortDirection — 'ASC' or 'DESC' (default).

### Get Comment Analytics
Docs: https://admanage.ai/api-docs/get-comments-analytics
Method: GET
Path: https://api.admanage.ai/v1/comments/analytics
Category: Comments
Mutating: no
Get aggregated comment analytics: sentiment distribution, top 10 ads by comment count, hidden/replied counts, and daily volume over time.

Query example:
accountId=act_123456789&startDate=2026-03-01&endDate=2026-03-31

Notes:
- Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive.
- Optional: accountId (or adAccountId) to filter by ad account.
- Optional: startDate, endDate (YYYY-MM-DD) for date range.
- If no date range provided, volumeOverTime defaults to the last 30 days.

### Reply to Comment
Docs: https://admanage.ai/api-docs/reply-to-comment
Method: POST
Path: https://api.admanage.ai/v1/comments/reply
Category: Comments
Mutating: yes
Reply to a Facebook ad comment. The reply is posted as the page that owns the ad.

Request body example:
```json
{
  "commentId": "1542661021111818_1245574530890886",
  "message": "Thanks for your feedback! Check out our website for more info.",
  "workspaceId": "workspace_abc"
}
```

Notes:
- commentId (required): Facebook comment ID from list_comments.
- message (required): reply text.
- workspaceId (optional): helps resolve the correct Facebook token if you have multiple workspaces.

### Hide Comment
Docs: https://admanage.ai/api-docs/hide-comment
Method: POST
Path: https://api.admanage.ai/v1/comments/hide
Category: Comments
Mutating: yes
Hide or unhide a Facebook ad comment from public view. Hidden comments are still visible to the page admin.

Request body example:
```json
{
  "commentId": "1542661021111818_1245574530890886",
  "hide": true,
  "workspaceId": "workspace_abc"
}
```

Notes:
- commentId (required): Facebook comment ID.
- hide (required): true to hide, false to unhide.
- workspaceId (optional): helps resolve the correct Facebook token.

### Top Ads
Docs: https://admanage.ai/api-docs/get-analytics-top-ads
Method: GET
Path: https://api.admanage.ai/v1/analytics/top-ads
Category: Analytics
Mutating: no
Get your top-performing ads sorted by spend, enriched with creative data (thumbnails, ad type detection, video sources). Supports Meta/Facebook and TikTok accounts with automatic platform detection. This endpoint does not currently cover Snapchat, Pinterest, Google Ads, or LinkedIn.

Query example:
accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-03-01&limit=10&page=1

Notes:
- This is the public API equivalent of the /reports/top-ads dashboard page.
- Top means ranked by spend descending.
- If you want the full ad list and plan to filter it yourself, use GET /v1/reports/query instead.
- Required: accountIds, startDate, endDate.
- Optional filters: campaignIds, adSetIds, adType (video | image | carousel).
- Pagination: limit (max 50, default 10), page (default 1).
- Platform is auto-detected from the account ID. Meta/Facebook (act_*) and TikTok are supported.
- Creative enrichment includes ad type detection (video/image/carousel), high-res thumbnails, and video sources.
- For Facebook, detailed metrics include actions, conversions, and purchase_roas arrays.
- If you need Pinterest tables, use GET /v1/reports/query. If you need Snapchat spend, use GET /v1/spend/daily. Google Ads has its own /v1/google-ads/* reporting endpoints.
- Date range cannot exceed 365 days.

### List Activity Log Entries
Docs: https://admanage.ai/api-docs/list-activity-log
Method: GET
Path: https://api.admanage.ai/v1/activity
Category: Activity Log
Mutating: no
List AdManage activity/change-log entries for your company. Captures every mutation performed through AdManage — launches, duplications, status flips, budget changes, bidding updates, edits, uploads, deletes, and automation runs — with actor, timestamp, platform, ad account, source→destination IDs, and per-item counts. Use to correlate platform changes with performance shifts.

Query example:
page=1&limit=25&platform=meta&status=success&action=launch_ads&startDate=2026-04-01&endDate=2026-04-21

Notes:
- Filter params: userId (matches userId or partial userEmail), platform, status, action, accountId, workspaceId, startDate, endDate.
- Platform values: "meta", "tiktok", "snapchat", "pinterest", "taboola", "axon", "google_ads", "reddit", "linkedin".
- Status values: "success", "failed", "partial", "attempted".
- Action values include: "launch_ads", "duplicate_campaign", "duplicate_adset", "duplicate_ad", "update_status", "update_budget", "update_bidding", "edit_ads", "upload_media", "delete_entities", etc.
- Dates accept YYYY-MM-DD or full ISO-8601 timestamps.
- Sorted by createdAt desc. page defaults to 1, limit defaults to 25 (max 100).
- Scoped to the API key's company — you only see activity within your company.
- For the full payload on a single entry (inputData, outputData, items, details), use GET /v1/activity/:id.

### Get Activity Log Entry
Docs: https://admanage.ai/api-docs/get-activity-log-entry
Method: GET
Path: https://api.admanage.ai/v1/activity/{id}
Category: Activity Log
Mutating: no
Fetch the full activity log entry for a single action, including inputData, outputData, items (per-ad results with error messages), details, thumbnails, and error string. Use after listing to drill into a specific change.

Notes:
- id: the numeric ID returned by GET /v1/activity.
- Returns 404 if the entry doesn't exist or belongs to a different company.

### List Changelog Entries
Docs: https://admanage.ai/api-docs/get-changelog
Method: GET
Path: https://admanage.ai/api/external/crm
Category: Changelog
Mutating: no
List published changelog entries in reverse chronological order. Returns the latest 20 entries. Auth via apiKey query parameter.

Query example:
apiKey=YOUR_CRM_API_KEY

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter (not Bearer header).
- Rate limited: 5 requests per second.
- Only returns published entries.

### Create Changelog Entry
Docs: https://admanage.ai/api-docs/post-changelog
Method: POST
Path: https://admanage.ai/api/external/crm
Category: Changelog
Mutating: yes
Create a new changelog entry programmatically. Useful for CI/CD pipelines, ChatGPT integrations, or automated release notes.

Query example:
apiKey=YOUR_CRM_API_KEY

Request body example:
```json
{
  "title": "Reddit Ads Integration",
  "content": "Launch ads directly to Reddit from AdManage.\n\n- Text, image, video, and carousel ad types\n- Full OAuth flow with automatic token refresh\n- Budget and targeting controls",
  "images": [],
  "category": "feature",
  "featured": false,
  "published": true,
  "authorName": "AdManage Team",
  "authorEmail": "team@admanage.ai",
  "createdAt": "2026-03-18T12:00:00.000Z"
}
```

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter (not Bearer header).
- Rate limited: 5 requests per second.
- Required fields: title, content, authorName, authorEmail.
- Optional fields: images (string[] of URLs), category (daily_update | weekly_update | feature | fix | improvement | update), featured (boolean), published (boolean, defaults true), createdAt (ISO-8601 timestamp — optional on create to backfill display and sort order).
- Category defaults to 'update' if not specified.

### Get Changelog Entry
Docs: https://admanage.ai/api-docs/get-changelog-entry
Method: GET
Path: https://admanage.ai/api/external/crm/{id}
Category: Changelog
Mutating: no
Get a single changelog entry by ID.

Query example:
apiKey=YOUR_CRM_API_KEY

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter.
- Replace {id} with the entry's numeric ID.

### Update Changelog Entry
Docs: https://admanage.ai/api-docs/patch-changelog-entry
Method: PATCH
Path: https://admanage.ai/api/external/crm/{id}
Category: Changelog
Mutating: yes
Update an existing changelog entry. All fields are optional — only include the fields you want to change.

Query example:
apiKey=YOUR_CRM_API_KEY

Request body example:
```json
{
  "title": "Updated Title",
  "content": "Updated markdown content.",
  "category": "improvement",
  "featured": true
}
```

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter.
- Replace {id} with the entry's numeric ID.
- All fields are optional. Only send what you want to update.
- Updatable fields: title, content, images, category, featured, published, authorName, authorEmail.

### Delete Changelog Entry
Docs: https://admanage.ai/api-docs/delete-changelog-entry
Method: DELETE
Path: https://admanage.ai/api/external/crm/{id}
Category: Changelog
Mutating: yes
Permanently delete a changelog entry by ID.

Query example:
apiKey=YOUR_CRM_API_KEY

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter.
- Replace {id} with the entry's numeric ID.
- This action is permanent and cannot be undone.

### Generate Cover Image
Docs: https://admanage.ai/api-docs/post-changelog-generate-image
Method: POST
Path: https://admanage.ai/api/external/crm/generate-image
Category: Changelog
Mutating: yes
Generate a professional cover image using AI (Google Gemini) and host it on the AdManage CDN. Returns a permanent URL you can use in the images array when creating or updating entries.

Query example:
apiKey=YOUR_CRM_API_KEY

Request body example:
```json
{
  "prompt": "A cover image for a changelog about Reddit Ads integration with social media icons and purple gradients"
}
```

Notes:
- Auth: Pass API key as ?apiKey=YOUR_KEY query parameter.
- Rate limited: 2 requests per second.
- The prompt describes the image to generate. Keep it concise (max 2000 chars).
- Images are generated with no text/words, using a tech/SaaS aesthetic.
- The returned URL is permanently hosted on the AdManage CDN (media.admanage.ai).
- Use the URL in the images array when creating/updating changelog entries.
- Workflow: 1) Generate image → 2) Create entry with the image URL in images array.

### List Pixels
Docs: https://admanage.ai/api-docs/get-conversions-pixels
Method: GET
Path: https://api.admanage.ai/v1/conversions/pixels
Category: Conversions
Mutating: no
List Meta pixels available on a Facebook ad account. Use the pixel ID to configure CAPI settings or when sending events.

Query example:
businessId=act_123456789&workspaceId=ws_abc

Notes:
- businessId (required): The ad account ID (e.g., act_123456789).
- workspaceId (optional): Scope the token lookup to a specific workspace.
- Uses your company's Facebook token to query Meta Graph API.

### Send Conversion Events
Docs: https://admanage.ai/api-docs/post-conversions-events
Method: POST
Path: https://api.admanage.ai/v1/conversions/events
Category: Conversions
Mutating: yes
Send custom events to Meta's Conversions API (CAPI) via your configured pixel. Events appear in Meta Ads Manager for optimization. PII fields (email, phone, etc.) are automatically SHA-256 hashed before sending to Meta.

Request body example:
```json
{
  "businessId": "act_123456789",
  "workspaceId": "ws_abc",
  "test_event_code": "TEST12345",
  "events": [
    {
      "event_name": "QualifiedLead",
      "event_time": 1710960000,
      "event_id": "unique-dedup-123",
      "action_source": "other",
      "user_data": {
        "em": "user@example.com",
        "ph": "+15551234567",
        "external_id": "crm-lead-abc123",
        "client_ip_address": "1.2.3.4"
      },
      "custom_data": {
        "value": 5000,
        "currency": "USD",
        "lead_status": "SQL",
        "crm_id": "abc123"
      }
    }
  ]
}
```

Notes:
- Prerequisites: Configure your Pixel ID and CAPI Access Token in Settings > Meta Conversions API for the ad account.
- businessId (required): The Facebook ad account ID (e.g., act_123456789).
- workspaceId (optional): For workspace-scoped config lookup.
- test_event_code (optional): Include this to see events in Meta Events Manager's Test Events tab without affecting production data.
- events (required): Array of 1-1000 events per request.
- event_name: Any string — standard events (Purchase, Lead, CompleteRegistration) or custom names (QualifiedLead, SQL, MQL).
- event_time: Unix timestamp in seconds. Must be within the last 7 days.
- event_id (optional): For deduplication if you send the same event from multiple sources.
- action_source: One of website, app, email, phone_call, chat, physical_store, system_generated, business_messaging, other. Falls back to your configured default.
- user_data: At least one identifier required (em, ph, fn, ln, external_id, client_ip_address, fbc, fbp). Plain-text values are automatically SHA-256 hashed. Already-hashed values (64-char hex) pass through unchanged.
- custom_data (optional): Arbitrary key-value pairs. Use value + currency for purchase events.
- Rate limit: 50 requests per minute (each can batch up to 1000 events = 50,000 events/min).
- Typical use: CRM/Google Sheets workflow triggers this endpoint when a lead status changes to SQL/MQL, sending the conversion event to Meta for ad optimization.

### Query Google Ads Account Metrics
Docs: https://admanage.ai/api-docs/get-google-ads-reports-query-channel
Method: GET
Path: https://api.admanage.ai/v1/reports/query
Category: Google Ads
Mutating: no
Return Google Ads ad, ad group, or campaign performance for connected Google Ads accounts. This duplicates the Reports section so Google Ads users can find metric sync examples in the Google Ads section.

Query example:
accountIds=7037703309&startDate=2026-05-19&endDate=2026-05-19&metrics=spend,impressions,clicks,conversions,conversionValue,roas,purchaseRoas,cpc,cpm,ctr,conversionRate,costPerResult&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=25

Notes:
- Use the Google Ads customer ID as accountIds, without dashes when possible.
- Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
- For large Google Ads accounts, prefer short date windows and paginate with limit/offset.
- The same endpoint is also documented in Reports as Query Google Ads Account Metrics.

### List Google Ads Campaigns
Docs: https://admanage.ai/api-docs/google-ads-campaigns
Method: GET
Path: https://api.admanage.ai/v1/google-ads/campaigns
Category: Google Ads
Mutating: no
Fetch cached Google Ads campaigns and ad groups from the database. Returns campaign structure with spend, impressions, clicks, conversions, and nested ad groups.

Query example:
accountId=7037703309

Notes:
- accountId (required): Google Ads account ID.
- Data is cached — use for instant reads. Sync happens automatically.
- Use GET /v1/reports/query when you need dashboard-style metric queries with date ranges, grouping, sorting, and pagination.

### Toggle Campaign Status
Docs: https://admanage.ai/api-docs/google-ads-toggle-status
Method: POST
Path: https://api.admanage.ai/v1/google-ads/campaigns/toggle-status
Category: Google Ads
Mutating: yes
Toggle a Google Ads campaign status between ENABLED and PAUSED.

Request body example:
```json
{
  "accountId": "7037703309",
  "campaignId": "123456789",
  "status": "PAUSED"
}
```

Notes:
- status: 'ENABLED' or 'PAUSED'.

### Rename Campaign
Docs: https://admanage.ai/api-docs/google-ads-rename
Method: POST
Path: https://api.admanage.ai/v1/google-ads/campaigns/rename
Category: Google Ads
Mutating: yes
Rename a Google Ads campaign.

Request body example:
```json
{
  "accountId": "7037703309",
  "campaignId": "123456789",
  "newName": "PMax - Q2 Prospecting"
}
```

### Duplicate Campaign
Docs: https://admanage.ai/api-docs/google-ads-duplicate-campaign
Method: POST
Path: https://api.admanage.ai/v1/google-ads/duplicate-campaign
Category: Google Ads
Mutating: yes
Duplicate a Google Ads campaign with all ad groups, ads, and keywords.

Request body example:
```json
{
  "campaignId": "123456789",
  "accountId": "7037703309",
  "newName": "Copy of PMax Campaign",
  "status": "PAUSED"
}
```

Notes:
- Copies all child ad groups, ads, and keywords.
- status: 'ENABLED' or 'PAUSED'.

### Duplicate Ad Group
Docs: https://admanage.ai/api-docs/google-ads-duplicate-ad-group
Method: POST
Path: https://api.admanage.ai/v1/google-ads/duplicate-ad-group
Category: Google Ads
Mutating: yes
Duplicate a Google Ads ad group with all ads and keywords.

Request body example:
```json
{
  "campaignId": "123456789",
  "adGroupId": "987654321",
  "accountId": "7037703309",
  "newName": "Copy of Ad Group",
  "status": "PAUSED"
}
```

### Duplicate Ad
Docs: https://admanage.ai/api-docs/google-ads-duplicate-ad
Method: POST
Path: https://api.admanage.ai/v1/google-ads/duplicate-ad
Category: Google Ads
Mutating: yes
Duplicate a single Google Ads ad (RSA, RDA, or generic types).

Request body example:
```json
{
  "adGroupId": "987654321",
  "adId": "111222333",
  "accountId": "7037703309",
  "status": "PAUSED"
}
```

Notes:
- Supports RSA, RDA, and generic ad types.

### Get Ad Details
Docs: https://admanage.ai/api-docs/google-ads-ad-details
Method: POST
Path: https://api.admanage.ai/v1/google-ads/ad-details
Category: Google Ads
Mutating: no
Fetch a Demand Gen ad's creative data for draft duplication. Returns headlines, descriptions, logos, videos, and CTAs.

Request body example:
```json
{
  "accountId": "7037703309",
  "adGroupId": "987654321",
  "adId": "111222333"
}
```

Notes:
- Read-only endpoint despite using POST method.

### Add Text Assets
Docs: https://admanage.ai/api-docs/google-ads-add-text-assets
Method: POST
Path: https://api.admanage.ai/v1/google-ads/add-text-assets
Category: Google Ads
Mutating: yes
Add text assets (headlines, long headlines, descriptions) to Performance Max asset groups.

Request body example:
```json
{
  "accountId": "7037703309",
  "assetGroupIds": [
    "customers/7037703309/assetGroups/123456"
  ],
  "headlines": [
    "Shop Our Sale",
    "Free Shipping Today"
  ],
  "longHeadlines": [
    "Discover the best deals on premium products"
  ],
  "descriptions": [
    "Get 50% off all items. Limited time offer."
  ]
}
```

Notes:
- All text arrays are optional but at least one must be provided.

### Add Video/Image Assets
Docs: https://admanage.ai/api-docs/google-ads-add-assets
Method: POST
Path: https://api.admanage.ai/v1/google-ads/add-assets
Category: Google Ads
Mutating: yes
Add video or image assets to PMax asset groups or Demand Gen campaign ads. Rate limited: 5 requests/minute.

Request body example:
```json
{
  "accountId": "7037703309",
  "assetGroupIds": [
    "customers/7037703309/assetGroups/123456"
  ],
  "videos": [
    {
      "youtubeVideoId": "dQw4w9WgXcQ"
    }
  ]
}
```

Notes:
- For PMax: pass assetGroupIds. For Demand Gen: pass campaignId + selectedAdIds.
- Videos use youtubeVideoId. Images use base64 + fieldType + aspectRatio.
- Rate limited: 5 requests per minute.

### Remove Asset
Docs: https://admanage.ai/api-docs/google-ads-remove-assets
Method: POST
Path: https://api.admanage.ai/v1/google-ads/remove-assets
Category: Google Ads
Mutating: yes
Remove an asset from a PMax asset group.

Request body example:
```json
{
  "accountId": "7037703309",
  "assetId": "12345678",
  "assetGroupId": "customers/7037703309/assetGroups/123456"
}
```

Notes:
- PMax campaigns require a minimum number of assets per type — removal may fail if at the minimum.

### Update Assets
Docs: https://admanage.ai/api-docs/google-ads-update-assets
Method: POST
Path: https://api.admanage.ai/v1/google-ads/update-assets
Category: Google Ads
Mutating: yes
Update text assets in PMax asset groups or Demand Gen ads. Text assets are immutable in Google Ads — the old asset is removed and a new one is created.

Request body example:
```json
{
  "accountId": "7037703309",
  "editedAssets": [
    {
      "assetId": "12345678",
      "text": "New Headline Text",
      "originalText": "Old Headline Text",
      "type": "headline",
      "assetGroupId": "customers/7037703309/assetGroups/123456"
    }
  ]
}
```

Notes:
- Text assets are immutable — updates delete the old and create a new one.

### Launch (Google Ads)
Docs: https://admanage.ai/api-docs/google-ads-launch
Method: POST
Path: https://api.admanage.ai/v1/google-ads/launch
Category: Google Ads
Mutating: yes
Orchestrated launch — creates a batch, runs all asset operations (add/remove/update text, videos, images), and updates the batch. Returns 202 Accepted. Rate limited: 3 requests/minute.

Request body example:
```json
{
  "accountId": "7037703309",
  "accountName": "My Google Ads Account",
  "assetGroupIds": [
    "customers/7037703309/assetGroups/123456"
  ],
  "assetGroupNames": [
    "PMax Asset Group 1"
  ],
  "headlines": [
    "Shop Our Sale"
  ],
  "descriptions": [
    "Get 50% off all items"
  ],
  "videos": [
    {
      "youtubeVideoId": "dQw4w9WgXcQ"
    }
  ]
}
```

Notes:
- Returns 202 Accepted — track progress via GET /v1/batch-status/:batchId.
- Rate limited: 3 requests per minute.
- Supports PMax (assetGroupIds) and Demand Gen (campaignId + selectedAdIds) campaigns.

### Upload Video to YouTube
Docs: https://admanage.ai/api-docs/youtube-upload
Method: POST
Path: https://api.admanage.ai/v1/youtube/upload-from-url
Category: YouTube
Mutating: yes
Upload a video to YouTube from a URL. Useful for getting YouTube video IDs required by Google Ads campaigns.

Request body example:
```json
{
  "videoUrl": "https://media.admanage.ai/uploads/abc123/creative.mp4",
  "title": "Product Demo - Q1 2026",
  "description": "Our latest product demo video",
  "privacy": "unlisted"
}
```

Notes:
- videoUrl (required): URL of the video to upload.
- privacy: 'private' (default), 'public', or 'unlisted'.
- Requires a connected YouTube/Google account.

### Read Google Sheet
Docs: https://admanage.ai/api-docs/read-google-sheet
Method: GET
Path: https://api.admanage.ai/v1/sheets/read
Category: Google Sheets
Mutating: no
Read cell data from a Google Sheet. Returns headers and rows as structured JSON. Uses your connected Google Drive token automatically, with service account fallback.

Query example:
url=https://docs.google.com/spreadsheets/d/1cy27K1nBMRvi6hL/edit&sheetName=Sheet1&range=A1:F50

Notes:
- url: Google Sheets URL or spreadsheet ID (required).
- sheetName: tab name to read (default: first tab).
- range: A1 notation range (default: all data).
- Auth: uses connected Google Drive token first, falls back to service account.
- Max 5000 rows returned per request.
- availableTabs lists all tabs so you can read others.

### Browse Google Drive
Docs: https://admanage.ai/api-docs/browse-google-drive
Method: GET
Path: https://api.admanage.ai/v1/drive/browse
Category: Uploading Media
Mutating: no
Browse Google Drive folders and files. Returns launchable media URLs for videos and images.

Query example:
folderId=root&scope=my-drive&pageSize=100&workspaceId=workspace_abc

Notes:
- folderId: Google Drive folder ID or 'root' (default).
- scope: 'my-drive' (default) or 'shared-with-me'.
- search: filter by filename.
- pageSize: max 1000, default 100.
- Requires a connected Google Drive account.

### Browse Dropbox
Docs: https://admanage.ai/api-docs/browse-dropbox
Method: GET
Path: https://api.admanage.ai/v1/dropbox/browse
Category: Uploading Media
Mutating: no
Browse Dropbox folders and files, including shared links. Returns launchable media URLs.

Query example:
path=&sharedLink=https://www.dropbox.com/scl/fo/abc123/AAA&limit=100

Notes:
- path: folder path (default: root).
- sharedLink: Dropbox shared link URL for accessing shared folders.
- search: filter by filename.
- limit: max 100, default 100.
- Requires a connected Dropbox account.

### Ad Delivery Statuses
Docs: https://admanage.ai/api-docs/ad-delivery-statuses
Method: GET
Path: https://api.admanage.ai/v1/adbatches/{id}/ad-delivery-statuses
Category: Batches
Mutating: no
Get the Meta delivery status (effective_status) of each ad in a completed batch. Poll until allSettled=true.

Query example:
refresh=true

Notes:
- id (path): batch ID or slug.
- refresh=true: bypass cache and re-fetch from Meta.
- Meta batches only — TikTok/other platforms return an empty result with a message.
- allSettled=true when all ads are in a terminal state (ACTIVE, PAUSED, DISAPPROVED, WITH_ISSUES, etc.).
- When allSettled=false, some ads are still pending — poll again after a few minutes.
- Pending ads are cached for 2 minutes; terminal results are cached permanently.

### Update Launch Defaults
Docs: https://admanage.ai/api-docs/update-launch-defaults
Method: PATCH
Path: https://api.admanage.ai/v1/launch-defaults
Category: Accounts
Mutating: yes
Update saved launch defaults for an ad account — page, Instagram, profile display names, copy, CTA, link, UTM tags, naming convention, and creative enhancements.

Request body example:
```json
{
  "accountId": "act_384730851257635",
  "title": "Check out our new collection!",
  "cta": "SHOP_NOW",
  "link": "https://example.com/shop",
  "page": "470703006115773",
  "facebookName": "Admanage",
  "insta": "17841471826052348",
  "instaName": "admanage.official",
  "urlTags": "utm_source=facebook&utm_medium=cpc&utm_campaign={{campaign.name}}",
  "launchPaused": true,
  "enhancedCreative": false
}
```

Notes:
- accountId (optional): defaults to user's default account.
- All fields are optional — only provided fields are updated.
- Supports: page, insta, facebookName, instaName, title, description, adDescription, cta, link, displaylink, urlTags, naming, namingSeparator, launchPaused, enhancedCreative, multiAdvertiser, instagramOnly, scalePostId, adCreationCutoff.

### Preview Automation Trigger
Docs: https://admanage.ai/api-docs/preview-automation-trigger
Method: GET
Path: https://api.admanage.ai/v1/automations/preview-trigger
Category: Automations
Mutating: no
Preview which ads or ad sets would match an automation rule's trigger conditions. Useful for testing rules before activating them.

Query example:
accountId=act_384730851257635&adSetFilterType=all&adStatusFilter=ACTIVE&criteria={"metric":"spend","operator":">","value":50,"lookbackDays":7}

Notes:
- accountId (required): ad account ID.
- criteria: JSON object with metric, operator (>, >=, <, <=, =), value, and lookbackDays.
- Supported metrics: spend, roas, cpm, cpc, ctr, impressions, conversions.
- adSetFilterType: 'all', 'contains', or 'specific'.
- adStatusFilter: 'all', 'ACTIVE', or 'PAUSED'.