# Admanage API (llms.txt) > v1 API for managing ad accounts, launching ads, querying reports, browsing media, duplicating campaigns/ad sets/ads, and automating workflows. Base URL: https://api.admanage.ai Versioned base: https://api.admanage.ai/v1 Full docs UI: https://admanage.ai/api-docs ## Authentication Every request (except GET /health, GET /v1/health and GET /llms.txt) MUST include an Authorization header with a Bearer token. **Header format:** ``` Authorization: Bearer YOUR_API_KEY ``` **Important:** Do NOT use x-api-key or any other header name. The ONLY accepted format is the Authorization header with a Bearer prefix. **Example:** ```bash curl -sS "https://api.admanage.ai/v1/adaccounts" \ -H "Authorization: Bearer ak_N-XqphL3DxvA..." ``` **Common mistakes:** - Using x-api-key: ak_... instead of Authorization: Bearer ak_... (will return 401) - Forgetting the "Bearer " prefix (will return 401) - Using query param ?api_key=... (not supported) API keys are company-scoped by default — all data returned is filtered to the company associated with the key. When a key is generated with a workspace restriction, listings and launches are limited to that workspace. ### Organization and workspace selection (OAuth MCP) OAuth MCP connectors can act on another organization the signed-in user currently belongs to: 1. GET /v1/organizations/mine lists current memberships, activeOrganizationId, currentCompany, connection (email/company/workspaceId/accessMode), and canSwitchOrganization. 2. Send the same Bearer token with x-admanage-organization-id: on each API request. There is no POST switch endpoint: REST selection is per request; omitting the header restores the connector's normal tenant resolution. 3. GET /v1/workspaces/mine lists the caller's workspace memberships inside that organization. Optionally send x-admanage-workspace-id: to choose one inside it. A workspace header alone never changes organizations. Organization selection requires an OAuth MCP connector. Ordinary customer API keys return data: [] with canSwitchOrganization: false and keep their existing tenant scope. Each selected-organization request checks live membership; unknown or revoked memberships return 403 without revealing whether the organization exists. Blocked organizations remain blocked. Existing read/write permissions are preserved. Without a workspace header, an explicit organization selection uses that organization's default workspace (or its first workspace when no default is configured), never the previous organization's workspace. A workspace header from another organization is rejected with 403. MCP tools: list_organizations lists memberships; switch_organization({ organizationId: "org_123" }) selects an organization for THIS MCP session and clears its old workspace selection. get_active_connection confirms the target. Use list_workspaces and switch_workspace for a workspace inside that organization. These tools change session state only, never the website, other MCP sessions, or ads. If authentication fails, the API returns: ```json { "success": false, "error": { "code": "unauthorized", "message": "Authorization header with Bearer token is required." } } ``` ## Error Shape ```json { "success": false, "error": { "code": "bad_request", "message": "human readable message", "requestId": "req-123" } } ``` ## Pagination The standard campaign, ad set, and ad list endpoints use `page` + `limit` query params (default `page=1`, `limit=25`, max `limit=100`) and return: ```json { "data": [...], "pagination": { "page": 1, "limit": 25, "total": 123, "totalPages": 5 } } ``` Results use a **stable sort** — the primary sort key (usually `lastUpdated` or `createdAt` desc) is paired with the unique `id` as a tiebreaker. This means looping `page=1..totalPages` with a fixed `limit` surfaces every row exactly once, even when many rows share the same `lastUpdated`/`createdAt` value (common right after a bulk sync). If rows are being written while you paginate, a row created mid-scan can still shift pages — filter by `accountId`/`campaignId` to narrow the snapshot if that matters. Pagination varies by endpoint; use its documented fields. For example, `/v1/tiktok/assets` uses `page` + `pageSize` (default 50, max 100) and returns `items`, `page`, and `pageSize` without a total count. `/v1/reports/query` uses `offset` + `limit` and returns `{ offset, limit, total, hasMore }` instead of `page`/`totalPages`. ## TikTok One / Creative Library Drafts Use the same Bearer API key for drafts and launches. Send the TikTok One material ID directly: 1. POST /v1/launch (or POST /v1/drafts) with ads[] using adAccountType="tiktok", adAccountId equal to the TikTok advertiser ID, and media: [{ "materialId": "7665361799190249490" }], plus the target adSets and ad copy. Send materialId as a string; 19-digit numbers lose precision as JSON numbers. 2. AdManage looks the material ID up in that advertiser's Creative Library and launches the existing video (the same as sending its media[].videoId). Nothing is uploaded. 3. Poll GET /v1/batch-status/{adBatchId} using the batch ID returned by launch. An unknown material ID, an image material ID, or a materialId that conflicts with a videoId in the same media item is rejected with a 400 before anything launches. To look up a video yourself, GET /v1/tiktok/assets?advertiserId=...&materialType=VIDEO&search= returns items[].id (the video ID) and materialId; send that as media: [{ "videoId": "v10033g50000d9gdbknog65gulih2vt0" }]. The asset endpoint accepts filename, material ID, video ID, or image ID searches. A material ID is not a Spark auth code: do not send it as sparkCode. Library video references reuse the existing video under the ad's selected TikTok identity; to run a creator's own post with their handle, use a Spark code. Saving a draft does not publish an ad; launch acceptance does not confirm platform success. ## Quick Launch (Fastest Path) To launch an ad in 3 API calls: 1. **GET /v1/launch-defaults** — returns your saved page, insta, display names, copy, CTA, link, UTM tags 2. **GET /v1/adsets?accountId=act_123** — returns ad sets with value/label ready for launch 3. **POST /v1/launch** — launch with defaults + ad sets + media URL, or with a Meta Post ID Then poll **GET /v1/batch-status/:id** until complete. Meta identity rule: pass `page` and `insta` as raw ID strings from `GET /v1/launch-defaults` or `GET /v1/profiles`. Also pass `facebookName` and `instaName` when available so AdManage can display readable profile chips. Do not pass profile objects like `{ "id": "..." }`. For pages without a linked Instagram account, use the synthetic instagram profile from `GET /v1/profiles` (`pageName: "Use Facebook Page"`) or set `page` and `insta` to the same Facebook Page id with `instaName: "Use Facebook Page"`. Example (uses defaults — only need media + ad sets): ```bash # Step 1: Get defaults curl -sS "https://api.admanage.ai/v1/launch-defaults" -H "Authorization: Bearer " # Step 2: Get ad sets curl -sS "https://api.admanage.ai/v1/adsets?accountId=act_384730851257635&limit=10" -H "Authorization: Bearer " # Step 3: Launch (fill in defaults from step 1, ad sets from step 2) curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [{ "adAccountId": "act_384730851257635", "title": "Stop wasting time on ad management", "description": "Launch ads 10x faster with AdManage", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "page": "470703006115773", "facebookName": "Admanage", "insta": "17841471826052348", "instaName": "admanage.official", "adSets": [{ "value": "120248289622780456", "label": "US Broad 25-44" }], "media": [{ "url": "https://media.admanage.ai/acme/creative.mp4" }] }] }' # Step 4: Poll until done curl -sS "https://api.admanage.ai/v1/batch-status/9912" -H "Authorization: Bearer " ``` ## Health - GET /health (same payload, no /v1 prefix) - GET /v1/health - GET /v1/health?deep=1 (also probes the database) Both forms report which build is serving traffic, so you can confirm a deploy shipped: `commit` is the full git SHA and `startedAt` is when the replica booted. Sample: ```bash curl -sS https://api.admanage.ai/health ``` Response: ```json { "success": true, "service": "api-admanage", "status": "ok", "version": "1.0.0", "commit": "2225b32e46e0a4c1f8b7d3a90c5e1f2a6b4d8c30", "branch": "main", "deploymentId": "dep_9f31c0", "environment": "production", "startedAt": "2026-08-05T13:00:00.000Z", "uptimeSeconds": 3600, "timestamp": "2026-08-05T14:00:00.000Z" } ``` The deep form adds `"db": "ok" | "error"` and answers 503 when the database is unreachable. Keep it off for load-balancer probes: those are the restart signal, and a transient database blip should not cycle replicas. ## Launch Creates an ad batch and dispatches to the launcher service. Returns immediately with batch ID for async polling. Supported via POST /v1/launch: facebook (Meta), tiktok, snapchat, pinterest, axon (AppLovin), taboola, linkedin, reddit, mintegral, moloco. Google Ads uses the dedicated POST /v1/google-ads/launch endpoint documented later in this file. To review a Google Ads launch before it goes live, save the same body as a draft (see "Google Ads drafts" under Launch Drafts). - POST /v1/launch Body: { ads: [...] } Each ad is fully self-contained with its own platform, account, ad sets, and media. ### ads[] fields | Field | Required | Description | |-------|----------|-------------| | adName | no | Custom ad name | | adAccountId | yes | Ad account ID (e.g. "act_123" for Meta, "mintegral_106572" for Mintegral, numeric for TikTok/Pinterest/Axon/LinkedIn/Reddit, UUID for Snapchat, provider-specific string for Taboola). Must be an ad account returned by GET /v1/adaccounts for this API key — anything else is rejected with 400 `ad_account_not_authorized` before any batch is created. The `act_` prefix is optional: "act_123" and "123" resolve to the same Meta account | | accountIds | no | Same-platform shorthand: array of ad account IDs to launch THIS one ad into. AdManage expands the ad into one row per account, reusing its copy, media, and adSets. All accounts must be on the same platform, and each must be returned by GET /v1/adaccounts. See "Multi-account launch" below | | accountAssignments | no | Per-account targets: array of `{ accountId, adAccountType, adSets, page/insta (Meta) or tikTokProfileId (TikTok) }`. Required when fanning one ad out across platforms, because ad set IDs and identities are account-specific. Each `accountId` must be returned by GET /v1/adaccounts. See "Multi-account launch" below | | workspaceId | no | Workspace ID for token lookup | | platform | no | "facebook", "tiktok", "snapchat", "pinterest", "axon", "taboola", "linkedin", "reddit", "mintegral", or "moloco". Auto-detected from adAccountId (act_* = facebook, mintegral_* = mintegral, moloco_* = moloco, UUID = snapchat) or adSets if omitted | | title | no | Headline / primary text | | description | no | Body text | | adDescription | no | Additional description | | cta | no | Call-to-action: "LEARN_MORE", "SHOP_NOW", "SIGN_UP", etc. | | link | no | Landing page URL | | sitelinks | Meta only | Site links (Meta site extensions) for this ad. Array of at least 3 objects, each with `title` and `url` (http or https). Repeat the same array on every ad in the batch — ads that omit it launch with sitelinks off. Optional `imageHash` must already be a Meta image hash in the ad account; image URLs are not uploaded at launch. Advantage+ / enhanced-creative defaults do not turn sitelinks on. Aliases: `siteLinks`, `siteLinksSpec`, and per-link `site_link_title` / `site_link_url` / `site_link_image_hash` | | displaylink | no | Display link shown on ad | | urlTags | no | UTM parameters appended to link | | page | Meta only | Facebook Page ID string to post from. Required for Meta. Pass the Page id as a string, not { "id": "..." } | | insta | Meta only | Instagram account ID string. Required for Meta unless the selected page is explicitly used as the Instagram identity | | adSets | yes | Array of ad sets to launch into (from GET /v1/adsets). Pass [] for Mintegral and use mintegralOffers instead; pass [] for Moloco and use molocoAdGroups instead | | media | yes, except existing-post/code flows | Array of media objects (videos or images). May be omitted for Meta Post ID ads, TikTok Spark codes, Meta partnership codes, and other documented existing-post flows | | type | no | "single", "multi", "carousel", "flexible" (default "single") | | launchPaused | no | Set true to create launched ads in PAUSED status instead of ACTIVE when supported. Can be set per ad; top-level launchPaused is also copied into simplified rows | | effectiveStoryId | Meta Post ID ads | Existing Meta Post ID / object_story_id in `pageId_postId` format. Creates the ad from the existing post and preserves engagement. Preferred field name. `pageId_postId` addresses a **Facebook Page** post — an Instagram media ID is a different namespace and is boosted as an Instagram post instead (see `instagramPostUrl`) | | postId | Meta Post ID ads | Alias for `effectiveStoryId`; use `pageId_postId` format | | objectStoryId / object_story_id / effective_object_story_id | Meta Post ID ads | Aliases for `effectiveStoryId` | | scalePostId | Meta only | Existing-post reuse toggle. Automatically enabled when a Post ID field is supplied | | instagramPostUrl | Meta only | Instagram `/p/`, `/reel/`, or `/tv/` permalink to boost as an existing organic post. The API resolves the post, pulls caption/media, and enables Post ID reuse | | instagramPostUrls | Meta only | Multiple Instagram permalinks to boost. Each URL becomes its own draft/launch row | | showProducts | Meta only | Convenience alias for manual catalogue/Show Products. Set true with catalogueId and productSetId to add "Show Products" to normal/multi-attached creatives | | catalogueAdConfig | Meta only | Full catalogue ads config object. Use for automatic Advantage+ catalogue ads, Hunch-style local-inventory single-image catalog ads, or manual "Show Products" | | catalogueId / catalogId | Meta only | Product catalog ID. Used by flat catalogue fields; maps to catalogueAdConfig.selectedCatalogue.id | | catalogueName / catalogName | Meta only | Product catalog display name | | productSetId | Meta only | Product set ID. Required for manual Show Products; automatic mode can resolve all-products when omitted | | productSetName | Meta only | Product set display name | | catalogueAdFormatMode | Meta only | "manual" for Show Products on supplied creatives, or "automatic" for Advantage+ catalog creative generation | | catalogueAdFormat | Meta only | "SINGLE_IMAGE", "SINGLE_VIDEO", "CAROUSEL", or "COLLECTION" (catalogue UI format — not Instant Experience Collection Ads; use `collectionAd` for storefront/canvas ads) | | collectionAd | Meta only | Instant Experience Collection Ads (storefront): `enabled`, `creationMode: "on_launch"`, `catalogId`, `selectedProductSetId`, product headline/description templates, `buttonLabel`, `buttonDestination`, optional prebuilt `instantExperienceId` / `mediaToExperienceMap` | | showProductsEnabled | Meta only | Manual catalogue Show Products toggle on `catalogueAdConfig` (products under the hero creative) | | catalogueAdLocalInventorySingleImage / catalogAdLocalInventorySingleImage / localInventorySingleImage | Meta only | Automatic catalog mode flag for the Hunch-style/local-inventory single-image payload. Use with `catalogueAdFormatMode: "automatic"` and `catalogueAdFormat: "SINGLE_IMAGE"` | | includeCarouselForCatalogue | Meta only | Manual mode toggle for product carousel extensions. Defaults to true when Show Products is enabled | | sparkCode | TikTok only | TikTok Spark Ads auth code. Launches from the creator's organic post — identity and post are resolved server-side. media is optional when set. | | partnershipCode | Meta only | Meta partnership ad code (e.g. "adcode-..."). Launches a branded-content / partnership ad from the creator's post. media is optional when set; still pass page and insta. | | selectedTikTokUserAccount | TikTok only | TikTok identity for ad attribution | | (TikTok identity) | TikTok only | Simplified ads[] launches pick the TikTok identity automatically: the one identity every existing ad in the target ad group already uses (Upgraded Smart+), otherwise the ad account's saved default TikTok profile in AdManage, otherwise TikTok's first available identity. To control it, set the ad account's default TikTok profile in AdManage. | | axonEndCards | Axon only | End cards: { "id": "" }, or { "url": "", "name": "" }, which AdManage uploads to AppLovin at launch (it waits for AppLovin's review). The name, or else the url's file name, must end in .html, .htm, .jpg, .jpeg, .png or .gif. Other urls work too but are uploaded again on every launch; a url hosted by AppLovin needs its "id" instead. | | axonDestinationUrl | Axon only | Destination URL used by the Axon launcher | | axonUrlTags | Axon only | Axon URL tags | | snapchatBrandName | Snapchat only | Brand name for Snapchat creatives | | snapchatProfileId | Snapchat only | Public profile ID | | snapchatPhoneNumberId | Snapchat AD_TO_CALL / AD_TO_MESSAGE | ID of a phone number verified in Snapchat Ads Manager (list them with GET /v1/snapchat/phone-numbers?snapchatAccountId=...). Required for Call and Text ads. | | snapchatTextMessage | Snapchat AD_TO_MESSAGE | Optional pre-filled SMS body, max 160 characters. | | snapchatAiDisclosure | Snapchat only | true declares the ad's image/video as AI-generated or AI-modified (Snapchat Ads Manager's "AI disclaimer"). Applied when the media is uploaded; previously uploaded media without it is uploaded again. | | pinterestBoardId | Pinterest only | Board ID for pin creation | | linkedinHeadline | LinkedIn only | LinkedIn headline override | | linkedinDescription | LinkedIn only | LinkedIn intro text override (max 3000 chars; 255 on carousel) | | linkedinAdDescription | LinkedIn only | LinkedIn description line under the headline, single image ads only (max 300 chars) | | linkedinCTA | LinkedIn only | LinkedIn CTA label | | linkedinAdFormat | LinkedIn only | "SINGLE_IMAGE", "VIDEO", or "CAROUSEL" | | linkedinObjective | LinkedIn only | Objective type such as WEBSITE_VISITS or LEAD_GENERATION | | carouselCards | LinkedIn carousel only | Array of { headline, landingUrl, imageUrn? } cards | | redditHeadline | Reddit only | Reddit headline override | | redditText | Reddit only | Reddit body text override | | redditCTA | Reddit only | Reddit CTA label | | redditAdType | Reddit only | "TEXT", "VIDEO", "IMAGE", or "CAROUSEL" (matches Reddit API) | | redditClickTrackers | Reddit only | Third-party click tracker URLs → the ad's click_trackers | | redditImpressionTrackers | Reddit only | Third-party impression tracker URLs → the ad's impression_trackers | | subreddit | Reddit only | Target subreddit when required by account setup | | taboolaCampaignAction | Taboola only | "existing" or "create" | | taboolaCampaignIds | Taboola only | Existing campaign IDs for launch | | taboolaCampaignNames | Taboola only | Existing campaign names for launch | | taboolaCta | Taboola only | Taboola CTA override | | mintegralOffers | Mintegral only | Array of { offerId, offerName?, campaignId, campaignName? }. All offers in one launch must belong to one campaign | | mintegralAdOutputs | Mintegral only | Format codes: 111 image, 211 video+endcard, 212 video+playable, 213 video, 311 playable; also supports 121, 122, 131 | | mintegralGeos | Mintegral only | Creative-set geo list; defaults to ["ALL"] | | mintegralIconMd5 | Mintegral only | Previously uploaded 512x512 icon MD5; required for outputs 122, 212, and 311 | | mintegralSetName | Mintegral only | Creative-set name; sanitized to letters, numbers, and underscores | | molocoAdGroups | Moloco only | Array of { adGroupId, campaignId, productId, adGroupName?, campaignName? } from GET /v1/manage/moloco/ad-groups. All must share one productId (app). Each ad becomes one Moloco creative group (its MP4 videos, JPEG/PNG/GIF images and at most one .html end card that every video in the group uses) added to every listed ad group. Every video needs an end card: the group's .html end card, or an endcard image with the video's orientation (e.g. ..._endcard_1080x1920.png for portrait); otherwise the launch is refused | | molocoCreativeGroupName | Moloco only | Creative group name; defaults to adName | ### Multi-account launch One POST /v1/launch can target several ad accounts. There are three routing modes and they compose: 1. **Per-ad `adAccountId`** — every entry in `ads[]` launches into its own account. Mix accounts freely in one request; nothing else is needed. 2. **`accountIds` (same-platform shorthand)** — put an array of account IDs on ONE ad to launch that same creative into all of them. Each account gets its own row reusing the ad's copy, media, and `adSets`. All accounts must be on the same platform. 3. **`accountAssignments` (full shape)** — give each target account its own ad sets and identity. Required when the accounts span platforms, because a Meta ad set ID is meaningless on a TikTok account. ```json { "adName": "Cross-platform creative", "adAccountId": "act_384730851257635", "media": [{ "url": "https://media.admanage.ai/acme/creative.mp4" }], "accountAssignments": [ { "accountId": "act_384730851257635", "adAccountType": "meta", "adSets": [{ "value": "120249198609970456", "label": "US Broad 25-44" }], "page": "470703006115773", "insta": "17841471826052348" }, { "accountId": "7486153503963054097", "adAccountType": "tiktok", "adSets": [{ "value": "1790000000000000001", "label": "TikTok Ad Group" }], "tikTokProfileId": "ident_123" } ] } ``` Rules: - Every ad account ID you pass (`adAccountId`, `accountIds[]`, `accountAssignments[].accountId`) must be an account this API key can launch into — i.e. one returned by GET /v1/adaccounts. The `act_` prefix is optional. Unknown accounts are rejected with 400 `ad_account_not_authorized` and no batch is created — see "Launch errors" below. - Ad sets are account-specific — always pass each account's own ad set IDs from GET /v1/adsets?businessId=... - If an ad omits `page`/`insta`, AdManage fills in each target account's saved default Facebook Page and Instagram profile. - Meta Post ID reuse is account-specific, so it is disabled for rows fanned out to several accounts; each expanded row launches a fresh ad. Responses: a same-platform multi-account request creates ONE batch and returns the normal 202 body. A cross-platform request is split into one batch per platform and the response adds a `batches[]` array — poll each `adBatchId` separately. ```json { "success": true, "message": "Launched 2 of 2 platform batches", "adBatchId": 9912, "adBatchSlug": "a1b2c3d4", "isAsync": true, "batches": [ { "platform": "facebook", "adBatchId": 9912, "adBatchSlug": "a1b2c3d4", "success": true }, { "platform": "tiktok", "adBatchId": 9913, "adBatchSlug": "e5f6a7b8", "success": true } ] } ``` ### adSets[] shape These come from GET /v1/adsets. Pass the objects returned by that endpoint. Minimum required fields: ```json { "value": "120248289622780456", "label": "US Broad 25-44" } ``` ### media[] shape Just provide the public URL — type and name are auto-derived from the filename extension: ```json { "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4" } ``` You can optionally include any of these fields: ```json { "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4", "name": "creative-1.mp4", "type": "video", "thumbnail": "https://media.admanage.ai/admanage.ai/thumb-ERER_DE_red123D4kWzVhn.jpg", "existingPostUrn": "urn:li:share:123456789", "portraitVariation": { "url": "https://media.admanage.ai/admanage.ai/card-1-story.png", "name": "card-1-story.png", "type": "image", "width": 1080, "height": 1920 } } ``` Auto-detection: .mp4/.mov/.avi/.webm = video, .png/.jpg/.gif/.webp = image. Note: `videos` is accepted as an alias for `media`. For Meta carousel cards, `portraitVariation` supplies a vertical/Reels/Stories placement variant for that card. It accepts the same media fields as the parent item; `url` is normalized to `preview` before launch. For Meta Post ID ads, omit `media` and pass `effectiveStoryId` (preferred) or `postId` at the ad level: ```json { "effectiveStoryId": "470703006115773_122123456789012345" } ``` You may also put the Post ID on a media item instead of `url`: ```json { "object_story_id": "470703006115773_122123456789012345" } ``` For Instagram post/reel URL boosts, pass `instagramPostUrl` or `instagramPostUrls` at the ad level instead of uploading media: ```json { "instagramPostUrl": "https://www.instagram.com/reel/BoostMe_123/" } ``` Supported URL shapes are `instagram.com/p/{shortcode}`, `instagram.com/reel/{shortcode}`, and `instagram.com/tv/{shortcode}`. The permalink must belong to the selected/default connected Instagram account and be found in its latest 500 Graph media posts. You can also paste a supported Instagram post URL as `media[].url`. Common Meta launch mistakes: - `page` and `insta` must be ID strings, not objects. - Carousel media items must each include `carouselTitle`. - If you want ads created paused, set `launchPaused: true` on each ad or at the top level of the simplified payload. - For Post ID ads, use `pageId_postId` format and do not upload the post media separately. - For Instagram post URL boosts, pass the permalink from the selected/default connected Instagram account and do not download/re-upload the media. - For Show Products, use `showProducts: true` with `catalogueId` and `productSetId`, or pass the full `catalogueAdConfig`. - For Meta sitelinks, pass `sitelinks` with at least 3 `{ "title", "url" }` entries on each ad. Fewer than 3 are rejected so the batch cannot silently launch with sitelinks off. - For Hunch-style catalog lead ads, use automatic catalogue mode with `format: "SINGLE_IMAGE"`, `localInventorySingleImage: true`, `media: []`, and a lead-form CTA. ### Example: Meta (Facebook/Instagram) Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Spring Sale - UGC", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "title": "Stop wasting time on ad management", "description": "Launch ads 10x faster with AdManage", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "displaylink": "admanage.ai", "urlTags": "utm_source=facebook&utm_medium=paid", "page": "470703006115773", "insta": "17841471826052348", "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ], "media": [ { "url": "https://media.admanage.ai/acme/Spring-Sale-UGC.mp4" } ] }, { "adName": "Spring Sale - Product Demo", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "title": "Stop wasting time on ad management", "description": "Launch ads 10x faster with AdManage", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "page": "470703006115773", "insta": "17841471826052348", "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ], "media": [ { "url": "https://media.admanage.ai/acme/Product-Demo.mp4" } ] } ] }' ``` ### Example: Meta Post ID Launch Creates an ad from an existing Facebook/Instagram post and preserves engagement. No media upload is needed. ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Spring Sale - Existing Post", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "effectiveStoryId": "470703006115773_122123456789012345", "page": "470703006115773", "insta": "17841471826052348", "launchPaused": true, "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ] } ] }' ``` ### Example: Meta Instagram Post URL Boost Creates an ad from an existing organic Instagram post/Reel permalink. No media upload is needed. ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Spring Sale - Existing IG Reel", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "instagramPostUrl": "https://www.instagram.com/reel/BoostMe_123/", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "page": "470703006115773", "insta": "17841471826052348", "launchPaused": true, "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ] } ] }' ``` ### Example: TikTok Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "TikTok - Creator Testimonial", "platform": "tiktok", "adAccountId": "7486153503963054097", "workspaceId": "workspace_abc", "title": "Check this out", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "adSets": [ { "value": "1857570827480306", "label": "Prospecting Ad Group" } ], "media": [ { "url": "https://media.admanage.ai/acme/ugc-creator-testimonial.mp4" } ] } ] }' ``` ### Example: TikTok Spark Ads (spark code) Launch Launch straight from a creator-shared Spark Ads auth code — no media upload needed. ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "TikTok Spark - Creator Post", "platform": "tiktok", "adAccountId": "7486153503963054097", "workspaceId": "workspace_abc", "sparkCode": "#TTAUTHCODE_abc123...", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "adSets": [ { "value": "1857570827480306", "label": "Prospecting Ad Group" } ] } ] }' ``` ### Example: Meta Partnership Code Launch Launch a branded-content / partnership ad from a creator-shared partnership ad code — no media upload needed. ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Meta Partnership - Creator Collab", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "partnershipCode": "adcode-abc123def456...", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "page": "470703006115773", "insta": "17841471826052348", "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ] } ] }' ``` ### Example: Snapchat Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Snap - Creative 1", "adAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109", "workspaceId": "workspace_abc", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "adSets": [ { "value": "4dc89846-99ca-4bd2-8806-180d1f137f0a", "label": "Landing Page Views Ad Set" } ], "media": [ { "url": "https://media.admanage.ai/acme/snap-creative.png" } ] } ] }' ``` ### Example: Pinterest Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Pinterest - Spring Collection", "platform": "pinterest", "adAccountId": "549769890977", "workspaceId": "workspace_abc", "title": "Spring collection", "description": "Shop our new arrivals", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "adSets": [ { "value": "2680088752242", "label": "Awareness Ad Group" } ], "media": [ { "url": "https://media.admanage.ai/acme/pin-creative.png" } ] } ] }' ``` ### Example: Axon Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Axon - Creative 1", "platform": "axon", "adAccountId": "1159321785", "workspaceId": "workspace_abc", "axonDestinationUrl": "https://admanage.ai/", "axonUrlTags": "utm_source=axon&utm_medium=paid", "cta": "LEARN_MORE", "axonEndCards": [ { "id": "12345678" }, { "url": "https://media.admanage.ai/acme/endcard.png", "name": "endcard.png" } ], "adSets": [], "media": [ { "url": "https://media.admanage.ai/acme/axon-creative.mp4" } ] } ] }' ``` ### Example: LinkedIn Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "LinkedIn - Video 1", "platform": "linkedin", "adAccountId": "513994704", "workspaceId": "workspace_abc", "title": "See what AdManage can automate", "description": "Launch and monitor paid social from one workflow.", "cta": "LEARN_MORE", "linkedinCTA": "LEARN_MORE", "link": "https://admanage.ai/", "adSets": [ { "value": "657885514", "label": "Website Visits Test" } ], "media": [ { "url": "https://media.admanage.ai/acme/linkedin-creative.mp4", "type": "video" } ] } ] }' ``` ### Example: Reddit Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Reddit - Video 1", "platform": "reddit", "adAccountId": "123456789", "workspaceId": "workspace_abc", "title": "See what AdManage can automate", "description": "Launch and monitor paid social from one workflow.", "cta": "LEARN_MORE", "subreddit": "marketing", "link": "https://admanage.ai/", "adSets": [ { "value": "adgroup-123", "label": "Reddit Test Ad Group" } ], "media": [ { "url": "https://media.admanage.ai/acme/reddit-creative.mp4", "type": "video" } ] } ] }' ``` ### Example: Taboola Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Taboola - Existing Campaign", "platform": "taboola", "adAccountId": "taboolaaccount-cedadmanageai", "workspaceId": "workspace_abc", "title": "Read the full guide", "description": "Launch Taboola items from AdManage", "link": "https://admanage.ai/", "taboolaCampaignAction": "existing", "taboolaCampaignIds": ["campaign-123"], "taboolaCampaignNames": ["Main Campaign"], "taboolaCta": "LEARN_MORE", "media": [ { "url": "https://media.admanage.ai/acme/taboola-creative.jpg" } ] } ] }' ``` ### Example: Mintegral Launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [ { "adName": "Summer Push 1", "platform": "mintegral", "adAccountId": "mintegral_106572", "workspaceId": "workspace_abc", "adSets": [], "mintegralOffers": [ { "offerId": "563332", "offerName": "Offer Name", "campaignId": "88", "campaignName": "Campaign Name" } ], "mintegralAdOutputs": [211], "mintegralGeos": ["ALL"], "media": [ { "url": "https://media.admanage.ai/acme/gameplay.mp4", "name": "gameplay.mp4", "type": "video" }, { "url": "https://media.admanage.ai/acme/endcard.png", "name": "endcard.png", "type": "image" } ] } ] }' ``` ### Launch Response (all platforms, 202 Accepted) ```json { "success": true, "message": "Ad launch initiated successfully", "adBatchSlug": "a1b2c3d4", "adBatchId": 9912, "isAsync": true } ``` After launching, poll GET /v1/batch-status/{adBatchId} until status is "success" or "error". ### Launch errors Launch payloads are validated **before any batch is created**. A rejected request creates no AdBatch, dispatches nothing to the launcher, and never shows up in GET /v1/batches. **`ad_account_not_authorized` (400)** — the request routes an ad to an ad account that is not connected to this AdManage account. Ad account IDs are checked against the accounts your API key's company owns, matched **with or without the `act_` prefix**: if GET /v1/adaccounts lists it, you can launch into it. ```json { "success": false, "error": { "code": "ad_account_not_authorized", "message": "Ad account \"act_123\" is not connected to this AdManage account. Call GET /v1/adaccounts to list the ad accounts this API key can launch into.", "requestId": "req_01H2XPZ4M9", "meta": { "unauthorizedAdAccountIds": ["act_123"], "fields": ["creativeState.globalDefaults.businessId"] } } } ``` - **Every offending ID is reported in ONE response** — there is no fail-on-first. `meta.unauthorizedAdAccountIds` holds the complete list, so a 50-row bulk launch is fixed in one edit instead of 50 retries. With more than one bad ID the message reads: `Ad accounts "act_123", "7029104" are not connected to this AdManage account. Call GET /v1/adaccounts to list the ad accounts this API key can launch into.` - **`meta.fields` are paths into the normalized creative state, not into your request body.** An `ads[]` payload is transformed into the internal `creativeState` shape before validation, so you get `creativeState.globalDefaults.businessId`, `creativeState.rows[N].businessId`, or `creativeState.rows[N].accountAssignments[M].businessId` — none of which appear literally in the JSON you sent. Use `meta.unauthorizedAdAccountIds` to locate the offending ads. (`ads[0].adAccountId` lands on `creativeState.globalDefaults.businessId` because it also seeds the batch-level defaults, and the first path per account wins.) - Enforced on POST /v1/launch, POST /v1/drafts, PATCH /v1/drafts/{id}, POST /v1/drafts/{id}/launch, and POST /v1/launch/from-draft. - On POST /v1/drafts/{id}/launch and POST /v1/launch/from-draft the check runs against the STORED creative state, so a draft or batch saved earlier is re-checked at launch: if one of its ad accounts has been disconnected since it was saved, the relaunch is rejected instead of failing later inside the platform launcher. - Not enforced on POST /v1/launch/organic — its `adAccountId` is only a label on the resulting batch, and the post is published to `pageId`/`instagramUserId`. ### Legacy format The old `creativeState` wrapper format is still fully supported: ```json { "creativeState": { "globalDefaults": { ... }, "rows": [ ... ] } } ``` ### Re-launch an existing batch - POST /v1/launch/from-draft Body: { batchId } ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch/from-draft" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"batchId": 9911}' ``` Response (202): ```json { "success": true, "message": "Ad launch initiated from draft", "adBatchSlug": "batch-abc123", "adBatchId": 9911, "isAsync": true } ``` ### Check Launch Batch Status Poll this endpoint after launching to track progress. - GET /v1/batch-status/:id Top-level `success` means the API request succeeded (auth OK). Use `batchSucceeded` and `summaryStatus` for whether the batch itself completed successfully. Per-ad Meta errors appear in `message`, `error`, `failedDetails`, and each `ads[]` item's `errorMessage` when available. ```bash curl -sS "https://api.admanage.ai/v1/batch-status/9911" \ -H "Authorization: Bearer " ``` ```json { "success": true, "batchSucceeded": false, "status": "processing", "summaryStatus": "in_progress", "progress": 62, "totalAds": 20, "successfulAds": 12, "failedAds": [], "message": "Launching..." } ``` ## Accounts + Profiles - GET /v1/adaccounts Query: page, limit ```bash curl -sS "https://api.admanage.ai/v1/adaccounts?page=1&limit=25" \ -H "Authorization: Bearer " ``` ```json { "data": [ { "id": 101, "accountId": "act_123456789", "accountName": "Main Account", "businessId": "act_123456789", "businessName": "Acme Holdings", "workspaceId": "workspace_abc", "company": "acme", "type": "facebook", "updatedAt": "2026-02-18T08:25:12.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 } } ``` - GET /v1/profiles Returns Facebook Pages, Instagram accounts, and Threads profiles associated with your ad account. Use the `pageId` values as the `page` (Facebook) and `insta` (Instagram) fields when launching ads. Query parameters: | Param | Required | Description | |-------|----------|-------------| | businessId | no | Ad account ID (e.g. "act_123"). If omitted, returns all profiles for your company | | workspaceId | no | Workspace ID. Auto-discovered from ad account if omitted | | type | no | Filter by type: "facebook", "instagram", or "threads" | | refresh | no | Set to "true" to bypass DB cache and fetch live from Facebook Graph API | ```bash # List all profiles (simplest — no params needed) curl -sS "https://api.admanage.ai/v1/profiles" \ -H "Authorization: Bearer " # Filter by ad account curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123" \ -H "Authorization: Bearer " # Filter by type curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123&type=facebook" \ -H "Authorization: Bearer " # Force refresh from Facebook Graph API curl -sS "https://api.admanage.ai/v1/profiles?businessId=act_123&refresh=true" \ -H "Authorization: Bearer " ``` Use the `pageId` from facebook profiles as the `page` field and `pageName` as `facebookName` in launch requests. Use the `pageId` from instagram profiles as the `insta` field and `pageName` as `instaName` in launch requests. When a page has no linked Instagram account, the API returns a synthetic instagram profile with `pageName: "Use Facebook Page"`, `useFacebookPageAsInstagram: true`, and `pageId` equal to the Facebook Page id. Pass that `pageId` as both `page` and `insta`, with `instaName: "Use Facebook Page"`. ```json { "success": true, "data": { "profiles": [ { "pageId": "470703006115773", "pageName": "Acme Brand Page", "type": "facebook", "pagePicture": "https://scontent.xx.fbcdn.net/...", "businessId": "act_123456789", "workspaceId": "workspace_abc" }, { "pageId": "17841405999999999", "pageName": "acme.official", "type": "instagram", "pagePicture": "https://scontent.xx.fbcdn.net/...", "businessId": "act_123456789", "workspaceId": "workspace_abc", "relatedPageId": "470703006115773", "followers": 15200 }, { "pageId": "470703006115773", "pageName": "Use Facebook Page", "type": "instagram", "businessId": "act_123456789", "workspaceId": "workspace_abc", "relatedPageId": "470703006115773", "isDarkInstagram": true, "useFacebookPageAsInstagram": true } ], "grouped": { "facebook": [ { "pageId": "470703006115773", "pageName": "Acme Brand Page", "..." : "..." } ], "instagram": [ { "pageId": "17841405999999999", "pageName": "acme.official", "..." : "..." } ], "threads": [] }, "counts": { "facebook": 1, "instagram": 1, "threads": 0 } } } ``` - GET /v1/user/extended2 Query: companyId? (required for external keys; company is accepted as an alias), userId? / email? (external keys only: which user in the company to describe; omit both for the company-level shape with null user fields), includeAccounts?, includeSettings?, limit? Returns userSettings (the user's Settings row for the company: naming, namingSeparator, copy defaults) when a user resolves, else null. ```bash curl -sS https://api.admanage.ai/v1/user/extended2 \ -H "Authorization: Bearer " ``` ```json { "id": "usr_01HXYZABCDEF", "email": "user@acme.com", "name": "Acme Operator", "company": "acme", "organizations": [ { "id": "org_123", "name": "Acme Holdings", "role": "admin" } ], "workspaces": [ { "id": "workspace_abc", "name": "Main Workspace", "defaultAdAccountId": "act_123456789" } ], "settings": { "timezone": "America/Los_Angeles", "currency": "USD" } } ``` - GET /v1/organizations/mine No query parameters. OAuth MCP only for organization discovery; ordinary customer keys return an empty data list with canSwitchOrganization: false. Response: { data: [{ id: "org_123", name: "Acme", company: "acme", defaultWorkspaceId: "workspace_abc" }], currentCompany: "acme", activeOrganizationId: "org_123", canSwitchOrganization: true, total: 1, connection: { email: "user@example.com", company: "acme", workspaceId: "workspace_abc", accessMode: "read_only" } } MCP: list_organizations / switch_organization. See Authentication for per-request organization headers. - GET /v1/workspaces/mine No query parameters. Lists the caller's workspace memberships inside the request's current organization. Response: { data: [{ id: "workspace_abc", name: "Main Workspace", company: "acme", organizationId: "org_123", adAccountCount: 2 }], currentCompany: "acme", total: 1 } MCP: list_workspaces (default membership listing) / switch_workspace (session default). Workspace-restricted API keys remain pinned. - GET /v1/workspaces Query: page, limit ```bash curl -sS "https://api.admanage.ai/v1/workspaces?page=1&limit=25" \ -H "Authorization: Bearer " ``` ```json { "data": [ { "id": "workspace_abc", "name": "Main Workspace", "company": "acme", "organizationId": "org_123", "metaAccountId": 12, "tiktokAccountId": null, "adAccounts": [ { "accountId": "act_123456789", "accountName": "Main Account", "platform": "facebook" } ] } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 } } ``` ## Templates - GET /v1/templates/ad-copy Query: page, pageSize (default 100, max 100), organizationId, businessId, adAccountId, includeTotal (default true; pass false for faster list responses) ```bash curl -sS "https://api.admanage.ai/v1/templates/ad-copy?page=1&pageSize=100" \ -H "Authorization: Bearer " ``` ```json { "data": [ { "id": "copy_abcd1234", "name": "UGC Static Template", "defaultTitle": "Free Trial", "defaultDescription": "Try it today", "businessId": "act_123456789", "workspaceId": "workspace_abc", "updatedAt": "2026-02-18T08:25:12.000Z" } ], "pagination": { "page": 1, "pageSize": 100, "total": 1, "totalPages": 1 } } ``` - GET /v1/templates/ad-copy/:id Query: organizationId, businessId, adAccountId ```bash curl -sS "https://api.admanage.ai/v1/templates/ad-copy/copy_abc" \ -H "Authorization: Bearer " ``` ```json { "id": "copy_abcd1234", "name": "UGC Static Template", "businessId": "act_123456789", "workspaceId": "workspace_abc", "templateData": { "globalDefaults": { "title": "Spring Launch", "description": "Top-performing variants", "cta": "SHOP_NOW" }, "rows": [ { "adName": "Creative 1", "headline": "New collection", "description": "Shop now", "videos": ["https://media.admanage.ai/example/ad-1.mp4"] } ] } } ``` ## Performance (Campaigns + Ad Sets) Retrieve campaign and ad set structures from your ad accounts. Data is synced from ad platforms — use these to discover IDs for launching, duplicating, or querying reports. ### Typical workflow 1. GET /v1/adaccounts → find your accountId (e.g. "act_384730851257635") and workspaceId 2. GET /v1/profiles?businessId=act_384730851257635 → get Facebook Page IDs (`page`) and Instagram IDs (`insta`) 3. GET /v1/campaigns?accountId=act_384730851257635 → list campaigns, get campaignId 4. GET /v1/adsets?campaignId=120247699100220456 → list ad sets in that campaign, get adSetId 5. POST /v1/launch → launch with page, insta, adSets, and media 6. GET /v1/reports/query?accountIds=act_384730851257635&metrics=spend,impressions,clicks → ad-level performance data ### GET /v1/campaigns List campaigns aggregated from ad sets. Campaigns are grouped from ad set records, so totalSpend and adSetCount reflect what's stored in AdManage. For TikTok accounts with no ad sets synced into AdManage (e.g. reporting-only API consumers), the authoritative campaign list is fetched live from TikTok — those rows carry campaign metadata (id, name, status, objective) with totalSpend/adSetCount of 0; use GET /v1/reports/query for spend. AppLovin accounts (platform "axon", alias "applovin"; pass the numeric AppLovin accountId) are read live from AppLovin, newest first, with totalSpend/adSetCount null. Each AppLovin row is the campaign's `ads[].adSets[]` entry for a platform "axon" launch: pass it whole (`value`, `label` and `campaignType`), so an APP campaign gets an APP creative set, and `pagination.truncated: true` means more campaigns exist than were read. AppLovin results can be up to 30 seconds old. With an accountId, AppLovin failures return an error status (400/404/429/502/504), never an empty list. Query parameters: | Param | Required | Description | |-------|----------|-------------| | page | no | Page number (default 1) | | limit | no | Results per page, max 100 (default 25) | | accountId | no | Filter by ad account ID (also accepts adAccountId) | | platform | no | Filter by platform: "facebook", "tiktok", "pinterest", "snapchat", "axon", "taboola", "linkedin", "reddit", "google_ads" | | status | no | Filter by campaign status: "ACTIVE", "PAUSED", etc. | | includeBudget | no | "true" adds current TikTok / Snapchat / AppLovin campaign budgets read live (see Current budgets below) | ```bash curl -sS "https://api.admanage.ai/v1/campaigns?page=1&limit=25&accountId=act_384730851257635" \ -H "Authorization: Bearer " ``` Response fields: | Field | Type | Description | |-------|------|-------------| | campaignId | string | Facebook/TikTok/Pinterest campaign ID | | campaignName | string | Campaign name | | platform | string | "facebook", "tiktok", "pinterest", "snapchat" | | accountId | string | Ad account ID (e.g. "act_384730851257635") | | status | string | Campaign status ("ACTIVE", "PAUSED", "DELETED", "ARCHIVED") | | totalSpend | number | Sum of spend across all ad sets in this campaign | | adSetCount | number | Number of ad sets in this campaign | | lastUpdated | string | ISO datetime of most recent ad set update | ```json { "data": [ { "campaignId": "120247699100220456", "campaignName": "Q1 Prospecting - Broad", "platform": "facebook", "accountId": "act_384730851257635", "status": "ACTIVE", "totalSpend": 842.22, "adSetCount": 4, "lastUpdated": "2026-02-19T21:12:45.787Z" }, { "campaignId": "120248100500330456", "campaignName": "Retargeting - Website Visitors", "platform": "facebook", "accountId": "act_384730851257635", "status": "ACTIVE", "totalSpend": 312.50, "adSetCount": 2, "lastUpdated": "2026-02-18T14:30:00.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 2, "totalPages": 1 } } ``` ### GET /v1/adsets List ad sets with status, spend, and ad count. Filter by campaign to drill into a specific campaign's ad sets. Query parameters: | Param | Required | Description | |-------|----------|-------------| | page | no | Page number (default 1) | | limit | no | Results per page, max 100 (default 25) | | campaignId | no | Filter by campaign ID | | accountId | no | Filter by ad account ID (also accepts adAccountId) | | workspaceId | no | Filter by workspace ID — resolves to the workspace's ad accounts | | platform | no | Filter by platform | | status | no | Filter by ad set status | | refresh | no | Force a live refresh for one account. Meta: resyncs the saved snapshot. TikTok (accountId, or a campaignId saved under one advertiser): lists ad groups live from TikTok, including Upgraded Smart+, with `freshness.source: "live"`; the saved snapshot is not modified, adSpend is 0 and adCount is null in live rows. If the live read fails, the saved snapshot is returned and freshness.skippedReason explains why. | | includeBudget | no | "true" adds current budgets read live from the platform: Meta `budget` object; TikTok / Snapchat / AppLovin flat budget fields (see Current budgets below) | For TikTok, pass `platform=tiktok&accountId=&refresh=true` to get the current ad groups (including newly created Upgraded Smart+ groups) straight from TikTok. Without `refresh=true`, TikTok rows come from the snapshot saved by the web app's Complete Refresh. For AppLovin (platform "axon", alias "applovin"), pass the numeric accountId and usually campaignId: rows are that account's creative sets read live from AppLovin, newest first, with `freshness.source: "live"` and no Meta refresh (refresh and detailsOnly are ignored; includeBudget adds the parent campaign's daily budget). The AppLovin read defaults to 5 rows when limit is omitted (each row carries its assets), and AppLovin results can be up to 30 seconds old. On these rows `value`/`label` are the PARENT CAMPAIGN, because a launch always creates a new creative set in it; each row also carries countries, languages, creativeSetUrl, `assets[]` and `launchAd`, a ready POST /v1/launch ad — send `{ ...launchAd, media: [{ "url": "...", "type": "video" }] }` to add a set like this one with its endcards. With an accountId, AppLovin failures return an error status, never an empty list. #### Current budgets (includeBudget=true) Pass `includeBudget=true` to read CURRENT budgets from the ad platform at request time (the saved snapshot holds no budgets). Read-only; it adds platform calls, so leave it off when browsing. - Meta (/v1/adsets only): each row gets a `budget` OBJECT { allocationLevel AD_SET|CAMPAIGN|UNSET, budgetType, currency, current { amount, minorUnits }, adSet, campaign, bidding, fetchedAt, source: "META_GRAPH_API" }. Meta campaign budgets are read through /v1/adsets?campaignId=…&includeBudget=true (`budget.campaign`). - TikTok, Snapchat, AppLovin (/v1/adsets and /v1/campaigns): each row gets flat fields `budget` (number, MAJOR currency units, e.g. 50 = 50.00), `budgetType` ("daily" | "lifetime"), `budgetLevel` ("campaign" | "adset" — the entity that owns the budget), `currency` (ISO code), `budgetSource` ("live" = read from the platform in this request, "cached" = an AppLovin read from the last 30 seconds) and `budgetFetchedAt`. `budget: null` means no budget is set at either level or it could not be read; see `budgetFreshness.errors`. - TikTok (pass accountId = advertiser id): ad groups and campaigns are listed live (no refresh=true needed), Upgraded Smart+ included. Upgraded Smart+ CBO budgets live on the campaign, so their ad-group rows report the campaign budget with budgetLevel "campaign". - Snapchat: saved ad squads/campaigns get the live ad-squad budget (`daily_budget_micro` / `lifetime_budget_micro`, converted from micro-currency) or, when the squad has none, the campaign budget; currency is the ad account's. - AppLovin: budgets are campaign-level daily budgets (`daily_budget_for_all_countries`); creative-set rows carry their parent campaign's budget. - The response-level `budgetFreshness` block carries { requested, fetchedAt, source, currency, errors[] }. ```bash curl -sS "https://api.admanage.ai/v1/adsets?campaignId=120247699100220456&limit=25" \ -H "Authorization: Bearer " ``` Response fields: | Field | Type | Description | |-------|------|-------------| | id | number | Internal AdManage ad set ID | | adSetId | string | Platform ad set ID (use this for duplication/delete) | | name | string | Ad set name | | value | string | Same as adSetId — launch-ready alias for ads[].adSets[].value | | label | string | Same as name — launch-ready alias for ads[].adSets[].label | | campaignId | string | Parent campaign ID | | campaignName | string | Parent campaign name | | account_id | string | Ad account ID (with act_ prefix for Meta) | | platform | string | "facebook", "tiktok", "pinterest", "snapchat" | | status | string | Ad set status ("ACTIVE", "PAUSED", etc.) | | campaignStatus | string | Parent campaign status | | adSpend | number | Total spend for this ad set | | adCount | number | Number of ads in this ad set | | lastUpdated | string | ISO datetime of last update | **Tip:** Each ad set object includes `value` and `label` fields, so you can pass them directly into `ads[].adSets[]` when launching. ```json { "data": [ { "id": 4521, "adSetId": "120248289622780456", "name": "US Broad - Women 25-44", "value": "120248289622780456", "label": "US Broad - Women 25-44", "campaignId": "120247699100220456", "campaignName": "Q1 Prospecting - Broad", "account_id": "act_384730851257635", "platform": "facebook", "status": "ACTIVE", "campaignStatus": "ACTIVE", "adSpend": 214.11, "adCount": 8, "lastUpdated": "2026-02-19T21:12:45.787Z" } ], "pagination": { "page": 1, "limit": 25, "total": 2, "totalPages": 1 } } ``` ### GET /v1/manage/list-ads List ads in a Facebook ad set or ad account directly from the Graph API. Use this to see which ads exist before deleting or editing them. Query parameters: | Param | Required | Description | |-------|----------|-------------| | adSetId | no* | Ad set ID to list ads from | | accountId | no* | Ad account ID (e.g. act_123) to list all ads | | status | no | Filter by effective status: "ACTIVE", "PAUSED", "ARCHIVED", "DELETED" | | limit | no | Max results (default 50, max 200) | | after | no | Meta Graph cursor from a previous response (`paging.cursors.after`) for the next page | | includePaging | no | Include sanitized `paging` cursors/URLs (auto-enabled when `after` is set) | | includeThumbnailUrl | no | Include creative thumbnail URLs | | workspaceId | no | Workspace ID for token lookup | *Either adSetId or accountId is required. ```bash curl -sS "https://api.admanage.ai/v1/manage/list-ads?adSetId=120248289622780456&limit=50&includePaging=true" \ -H "Authorization: Bearer " ``` Response: ```json { "success": true, "data": [ { "id": "120249137908810789", "name": "Video Ad - US Broad", "status": "ACTIVE", "effectiveStatus": "ACTIVE", "createdTime": "2026-02-18T08:25:12+0000", "thumbnailUrl": "https://..." } ], "count": 12, "paging": { "cursors": { "before": "...", "after": "..." }, "next": "https://graph.facebook.com/..." } } ``` ## Batches - GET /v1/adbatches Query: page, limit, search, status, channel, user, adAccountId, workspaceId, privateHistory, dateFrom, dateTo, companyId? (required for external keys; company is accepted as an alias) ```bash curl -sS "https://api.admanage.ai/v1/adbatches?page=1&limit=25&adAccountId=act_123" \ -H "Authorization: Bearer " ``` ```json { "data": [ { "id": 9911, "slug": "batch_2026_02_18_9911", "status": "processing", "user": "user@acme.com", "workspaceId": "workspace_abc", "adAccountId": "act_123456789", "createdAt": "2026-02-18T08:25:12.000Z", "updatedAt": "2026-02-18T08:28:41.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 } } ``` - GET /v1/adbatches/stats Launched batches and ads grouped in one call (same counting as the admin organization page). Query: groupBy (channel | adAccountId | user, required), dateFrom?, dateTo? (YYYY-MM-DD; omit both for all time), workspaceId?, companyId? (required for external keys; company is accepted as an alias) ```bash curl -sS "https://api.admanage.ai/v1/adbatches/stats?groupBy=adAccountId" \ -H "Authorization: Bearer " ``` ```json { "data": [{ "key": "act_1951928428859901", "name": "Wild Cosmetics US", "batches": 4210, "ads": 18950 }], "totals": { "batches": 10555, "ads": 47066 } } ``` key is the channel, ad account id, or launcher email; name is the ad account name for groupBy=adAccountId, otherwise null. A workspace-locked key only ever counts its own workspace; workspaceId can only narrow a company-wide key's results. - GET /v1/adbatches/:id Query: companyId? (required for external keys; company is accepted as an alias) ```bash curl -sS "https://api.admanage.ai/v1/adbatches/9911" \ -H "Authorization: Bearer " ``` ```json { "id": 9911, "slug": "batch_2026_02_18_9911", "status": "processing", "workspaceId": "workspace_abc", "adAccountId": "act_123456789", "batchData": { "creativeState": { "globalDefaults": { "title": "Spring Launch", "description": "Top-performing variants", "cta": "SHOP_NOW" }, "rows": [ { "adName": "Creative 1", "headline": "New collection" } ] } } } ``` - GET /v1/adbatches/:id/ad-delivery-statuses Query: refresh (optional, "true" to bypass cache) Check the Meta delivery status of each ad in a completed batch. Returns effective_status (ACTIVE, PENDING_REVIEW, WITH_ISSUES, CAMPAIGN_PAUSED, etc.) for every ad. Results are persisted to the database. If all ads are in a terminal state (ACTIVE, PAUSED, DISAPPROVED, etc.), allSettled=true and cached permanently. If some ads are still pending, results are cached for 2 minutes before re-fetching. Every response also includes the launch-stage error context (`batchStatus`, `summaryStatus`, `launchError`, `launchFailedDetails`, `launchErrorMessage`, `finalMessage`) so callers can see when the batch failed before any ads were created — e.g. a Meta video-upload error — instead of getting an empty `adDeliveryStatuses` map. ```bash curl -sS "https://api.admanage.ai/v1/adbatches/9911/ad-delivery-statuses" \ -H "Authorization: Bearer " ``` ```json { "success": true, "batchId": 9911, "adDeliveryStatuses": { "120250610776790456": { "effectiveStatus": "ACTIVE", "status": "ACTIVE", "configuredStatus": "ACTIVE", "issuesInfo": [], "checkedAt": "2026-03-30T12:00:00.000Z" } }, "allSettled": true, "fromCache": false, "checkedAt": "2026-03-30T12:00:00.000Z", "batchStatus": "success", "summaryStatus": "success", "launchError": null, "launchFailedDetails": null, "launchErrorMessage": null, "finalMessage": "5 ads launched" } ``` When a batch fails at the launch stage (e.g. video upload error) and no ads are created, the response surfaces the real error: ```json { "success": true, "batchId": 475476, "adDeliveryStatuses": {}, "fromCache": false, "message": "No videos uploaded or reused: Facebook API Error: Unable to fetch video file from URL. (Code: 389)", "batchStatus": "error", "summaryStatus": "error", "launchError": [{ "message": "No videos uploaded or reused: Facebook API Error: ..." }], "launchFailedDetails": null, "launchErrorMessage": "No videos uploaded or reused: Facebook API Error: Unable to fetch video file from URL. (Code: 389)", "finalMessage": "0 ads completed" } ``` - GET /v1/launch/batch/:batchId Same as batch-status: top-level `success` is the HTTP/API call; `batchSucceeded` reflects whether the launch batch finished without errors. `results.successful` lists only successful rows from stored launch data (failed rows are in `results.failed`). ```bash curl -sS "https://api.admanage.ai/v1/launch/batch/9911" \ -H "Authorization: Bearer " ``` ```json { "success": true, "batchSucceeded": false, "batch": { "id": 9911, "status": "processing", "progress": { "total": 20, "processed": 12, "successful": 11, "failed": 1, "percentage": 60 }, "alreadyProcessing": false } } ``` ## Reports (Ad Performance Data) Query ad performance data across platforms. Uses BigQuery for Facebook, falls back to platform-specific APIs for TikTok and Pinterest. Each row represents one ad (or grouped entity), with the metrics you requested. ### GET /v1/reports/query The main reporting endpoint. Returns ad-level performance data with thumbnails. Query parameters: | Param | Required | Description | |-------|----------|-------------| | accountIds | yes | Comma-separated ad account IDs. Meta IDs use the act_ prefix ("act_384730851257635"); TikTok and Google Ads IDs are plain numbers with no prefix (e.g. "1234567890"); Snapchat IDs are UUIDs. Mix platforms in one query: "act_384730851257635,1234567890". Call GET /v1/adaccounts to discover the exact IDs for every platform you've connected. | | startDate | yes | Start date (YYYY-MM-DD) | | endDate | yes | End date (YYYY-MM-DD) | | metrics | yes | Comma-separated metric names (see below) | | groupBy | no | Dimension to group by (default: "adId"). Options: adId, adName, campaignName, adsetName, landingPage, assetType, creative, videoAsset, imageAsset, body, title, callToActionType, adStatus, objective | | timeIncrement | no | Google Ads only: "day" or "week" returns one row per grouped entity per day or Monday-start week (clipped to the range, with dateStart/dateStop), e.g. groupBy=adsetName&timeIncrement=week for ad-group week over week in one call. | | sortBy | no | Metric to sort by (e.g. "spend", "impressions") | | sortDirection | no | "ASC" or "DESC" (default DESC) | | limit | no | Max rows per page (default 25, max 500). Use offset to page beyond one response — pagination.total and hasMore reflect the full result set. | | offset | no | Skip rows for pagination (default 0) | | filters | no | JSON-encoded filters array (see filter operators below) | | filterOperator | no | "AND" or "OR" — how multiple filters combine (default "AND") | | excludePatterns | no | Comma-separated patterns to strip from ad names when grouping (e.g. "- Copy,- v2") | | workspaceId | no | Workspace ID for token resolution (TikTok/Pinterest) | Common metrics (performance): - spend, impressions, clicks, reach, outboundClicks, linkClicks, landingPageViews, results Common metrics (calculated): - cpm, ctr, clicksCost (CPC), frequency, costPerResult, roas Video metrics: - videoViews (3s), thruPlays (15s), videoP025Watched, videoP050Watched, videoP075Watched, videoP100Watched - hookRate (3s views / impressions), vtr (100% watched / impressions), holdPlay (thruPlays / 3s views) Conversion metrics: - purchases, purchaseValue, purchaseRoas, addToCart, registrations, leads, contentViews, appInstalls Use GET /v1/reports/fields for the complete list with descriptions. ### Attribution window Every response carries `metadata.attribution`, so a spend or conversion figure is never ambiguous: | mode | What it means | |------|---------------| | meta_account_default | No `action_attribution_windows` override was sent to Meta, so conversions come back under each ad account's own default attribution setting (the one configured in Ads Manager). This is the default for plain metrics like `purchases` and `roas`. | | explicit_windows | You requested `attr_*` metrics, so those exact windows were requested from Meta. `metadata.attribution.windows` lists them (e.g. `["28d_click"]`) and `windowLabels` gives the readable form. Any non-`attr_*` conversion metric in the same response still uses the account default. | | platform_default | A non-Meta account (TikTok, Google Ads, Snapchat, Pinterest, AppLovin) — the platform applies its own attribution model. Explicit windows are Meta-only. | To pin a window, request the attribution field instead of the plain metric. The naming is `attr__`, with `_cost_`, `_value_`, and `_roas_` variants: - Windows: `28d_click`, `7d_click`, `1d_click`, `7d_view`, `1d_view`, `1d_ev` (1-day engaged view) - Examples: `attr_purchases_28d_click`, `attr_purchases_value_7d_click`, `attr_purchases_roas_28d_click`, `attr_leads_cost_1d_click` ```bash # 28-day-click purchases and ROAS, instead of the account default curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,attr_purchases_28d_click,attr_purchases_roas_28d_click&groupBy=adId" \ -H "Authorization: Bearer " ``` ```bash curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,clicks,ctr,cpm,reach,videoViews,hookRate,purchases,purchaseValue,roas,costPerResult&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=10" \ -H "Authorization: Bearer " ``` Response fields per row: | Field | Type | Description | |-------|------|-------------| | adId | string | Ad ID (or grouped dimension value) | | adName | string | Ad name (included automatically) | | campaignName | string | Parent campaign name | | adsetName | string | Parent ad set name | | thumbnailUrl | string | Creative thumbnail URL | | imageUrl | string | Direct image asset URL. Request via `metrics=imageUrl`. Null for video-only ads. | | videoUrl | string | Direct video asset URL. Request via `metrics=videoUrl`. Null for image-only ads. | | _accountId | string | Ad account ID this row belongs to | | spend | number | Total amount spent | | impressions | number | Total impressions | | clicks | number | Total clicks | | ctr | number | Click-through rate (clicks / impressions) | | cpm | number | Cost per mille (spend / impressions * 1000) | | (other metrics) | number | As requested in the metrics parameter | ```json { "success": true, "data": [ { "adId": "120247682651440456", "adName": "UGC Creator Testimonial - v2", "campaignName": "Q1 Prospecting - Broad", "adsetName": "US Broad - Women 25-44", "thumbnailUrl": "https://files.admanage.app/act_384730851257635/120247682651440456", "_accountId": "act_384730851257635", "spend": 192.06, "impressions": 46650, "clicks": 492, "ctr": 0.01054, "cpm": 4.117, "reach": 38200, "videoViews": 12800, "hookRate": 0.274, "purchases": 8, "purchaseValue": 640.00, "roas": 3.33, "costPerResult": 24.01 }, { "adId": "120247704303600456", "adName": "Product Demo - Spring Collection", "campaignName": "Q1 Prospecting - Broad", "adsetName": "US Broad - Men 25-54", "thumbnailUrl": "https://files.admanage.app/act_384730851257635/120247704303600456", "_accountId": "act_384730851257635", "spend": 50.50, "impressions": 22910, "clicks": 188, "ctr": 0.0082, "cpm": 2.204, "reach": 19400, "videoViews": 5600, "hookRate": 0.244, "purchases": 2, "purchaseValue": 180.00, "roas": 3.56, "costPerResult": 25.25 } ], "pagination": { "offset": 0, "limit": 10, "total": 5, "hasMore": false }, "metadata": { "platform": "facebook", "source": "bigquery" } } ``` **Account validation:** The endpoint validates that the requested accountIds belong to your API key. If some accounts are invalid, valid ones are queried and a warning is returned for the skipped ones. **Diagnostics (metadata.warnings):** When data is empty or partially unavailable, the response includes `metadata.warnings` — an array of human-readable strings explaining why. Examples: - `"Reporting pipeline not configured for account act_123. Connect the account in AdManage settings to enable performance data."` - `"No Facebook access token found. Ensure a token is connected in AdManage settings."` - `"The following account IDs were skipped (not found for this API key): act_999"` - `"No data found in reporting pipeline for the requested date range."` - `"No Google Ads access token found. Connect Google Ads in AdManage settings."` - `"No Google Ads data found for the requested date range. Verify the account is connected and has spend in this window."` - `"AppLovin account 1415187: add the Reporting API Key in Integrations → AppLovin to enable performance data."` **Platforms supported by /v1/reports/query:** Meta/Facebook, TikTok, Pinterest, Google Ads, and AppLovin (Axon). Google Ads reporting is returned from the Google Ads API fallback and includes campaign/ad group level performance where available. **Snapchat accounts:** UUID account IDs (type "snapchat" in /v1/adaccounts). Rows are fetched live from Snapchat's Measurement API — one row per ad with spend, impressions, swipe-ups (reported as clicks), reach, frequency, video views, completions, purchases, and purchase value/ROAS, joined with ad/ad squad/campaign names. Reporting rotates through every connected Snapchat login until one has access to the account. **AppLovin (Axon) accounts:** Numeric account IDs (type "axon" in /v1/adaccounts). Rows are fetched live from AppLovin's Asset Reporting API — one row per creative asset with spend, impressions, clicks, CTR, CPC, and CPM; `groupBy=campaignName` or `groupBy=adsetName` aggregates them (AppLovin's creative set maps to adsetName). AppLovin enforces a 45-day lookback: wider windows are clamped to the most recent 45 days with a warning. Conversion/ROAS metrics and filters are not available. Requires the account's Reporting API Key (separate from the manage key) connected in Integrations → AppLovin. **Google Ads account IDs:** Unlike Meta (`act_...`), Google Ads account IDs are plain 10-digit customer IDs with no prefix and no dashes (e.g. `1234567890`, not `123-456-7890`). They are not included automatically — you must add them to `accountIds` alongside your Meta/TikTok IDs, otherwise Google spend will not appear in the response. Use GET /v1/adaccounts to look up your Google account IDs (they are returned with `"type": "google_ads"`). Example mixing Meta + Google in one query: ```bash curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635,1234567890&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,clicks" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [], "pagination": { "offset": 0, "limit": 25, "total": 0, "hasMore": false }, "metadata": { "platform": "facebook", "source": "none", "warnings": [ "Reporting pipeline not configured for account act_123. Connect the account in AdManage settings to enable performance data.", "No Facebook access token found. Ensure a token is connected in AdManage settings." ] } } ``` **Filter operators:** EQUALS, NOT_EQUALS, HIGHER_THAN, LOWER_THAN, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, IN, NOT_IN, BETWEEN, NOT_BETWEEN, EMPTY, NOT_EMPTY Example: Group by campaign name: ```bash curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,clicks,purchases,roas&groupBy=campaignName&sortBy=spend&sortDirection=DESC&limit=25" \ -H "Authorization: Bearer " ``` Example: Group by ad set name: ```bash curl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_384730851257635&startDate=2026-02-01&endDate=2026-02-20&metrics=spend,impressions,ctr,roas&groupBy=adsetName&sortBy=spend&sortDirection=DESC&limit=25" \ -H "Authorization: Bearer " ``` ### GET /v1/reports/meta/reach-composition Dedicated Meta reach-composition endpoint. Mirrors the core calculations behind the AdManage reach page and returns monthly reach, cumulative reach, and incremental reach (same as net-new reach) for one ad account. Query parameters: | Param | Required | Description | |-------|----------|-------------| | accountId | yes | One Meta ad account ID (e.g. "act_384730851257635") | | startDate | yes | Start date (YYYY-MM-DD) | | endDate | yes | End date (YYYY-MM-DD) | | campaignIds | no | Comma-separated campaign IDs to filter | | countries | no | Comma-separated country codes (e.g. "US,CA") | | workspaceId | no | Workspace ID for token resolution | ```bash curl -sS "https://api.admanage.ai/v1/reports/meta/reach-composition?accountId=act_384730851257635&startDate=2025-01-01&endDate=2025-03-31" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "month": "2025-01", "monthLabel": "Jan 2025", "reach": 120000, "cumulativeReach": 120000, "rawNetNewReach": 120000, "netNewReach": 120000, "incrementalReach": 120000, "previouslyReached": 0, "pctNetNew": 100, "impressions": 210000, "frequency": 1.75, "spend": 4200.5 }, { "month": "2025-02", "monthLabel": "Feb 2025", "reach": 90000, "cumulativeReach": 176000, "rawNetNewReach": 56000, "netNewReach": 56000, "incrementalReach": 56000, "previouslyReached": 34000, "pctNetNew": 62.22, "impressions": 171000, "frequency": 1.9, "spend": 3850.25 } ], "summary": { "totalCumulativeReach": 176000, "lastMonthNetNewReach": 56000, "lastMonthIncrementalReach": 56000, "avgPctNetNew": 81.11, "avgFrequency": 1.825, "trend": "down" }, "filters": { "campaigns": [ { "id": "12020001", "name": "Q1 Broad", "spend": 1425.32, "status": "ACTIVE", "isActive": true } ], "countries": [ { "code": "US", "name": "US", "spend": 1300.22 } ] }, "metadata": { "platform": "facebook", "source": "facebook_api" } } ``` Notes: - `incrementalReach` is an alias of `netNewReach`. - Each period includes `spend` (account-currency total for that month). - When campaign filters are applied, cumulative reach is rebased to the filtered window so the first active month starts at zero baseline. - If access is missing or the token is expired, the endpoint returns empty data with details in `metadata.warnings` and may include `metadata.requiresReauth=true`. ### GET /v1/reports/fields Returns all available dimensions and metrics for building report queries. Each entry includes name, label, type, format, and description. ```bash curl -sS "https://api.admanage.ai/v1/reports/fields" \ -H "Authorization: Bearer " ``` ```json { "success": true, "dimensions": [ { "name": "adId", "label": "Unique Ad", "type": "dimension" }, { "name": "adName", "label": "Ad name", "type": "dimension" }, { "name": "adsetName", "label": "Adset name", "type": "dimension" }, { "name": "campaignName", "label": "Campaign name", "type": "dimension" }, { "name": "landingPage", "label": "Landing page", "type": "dimension" }, { "name": "assetType", "label": "Ad type", "type": "dimension" }, { "name": "creative", "label": "Creative", "type": "dimension" }, { "name": "videoAsset", "label": "Video", "type": "dimension" }, { "name": "imageAsset", "label": "Image", "type": "dimension" }, { "name": "body", "label": "Copy", "type": "dimension" }, { "name": "title", "label": "Headline", "type": "dimension" }, { "name": "callToActionType", "label": "Call to action", "type": "dimension" }, { "name": "adStatus", "label": "Ad status", "type": "dimension" }, { "name": "objective", "label": "Campaign Objective", "type": "dimension" } ], "metrics": [ { "name": "spend", "label": "Amount Spent", "type": "metric", "format": "MONEY" }, { "name": "impressions", "label": "Impressions", "type": "metric", "format": "NUMBER" }, { "name": "clicks", "label": "Clicks", "type": "metric", "format": "NUMBER" }, { "name": "reach", "label": "Reach", "type": "metric", "format": "NUMBER" }, { "name": "videoViews", "label": "3 second video views", "type": "metric", "format": "NUMBER" }, { "name": "thruPlays", "label": "Thruplay", "type": "metric", "format": "NUMBER" }, { "name": "purchases", "label": "Purchases", "type": "metric", "format": "NUMBER" }, { "name": "purchaseValue", "label": "Purchase Value", "type": "metric", "format": "MONEY" }, { "name": "leads", "label": "Leads", "type": "metric", "format": "NUMBER" }, { "name": "results", "label": "Results", "type": "metric", "format": "NUMBER" }, { "name": "cpm", "label": "CPM", "type": "calculated", "format": "MONEY" }, { "name": "ctr", "label": "CTR", "type": "calculated", "format": "PERCENTAGE" }, { "name": "clicksCost", "label": "CPC", "type": "calculated", "format": "MONEY" }, { "name": "frequency", "label": "Frequency", "type": "calculated", "format": "FLOAT" }, { "name": "hookRate", "label": "Hook Rate", "type": "calculated", "format": "PERCENTAGE" }, { "name": "vtr", "label": "VTR", "type": "calculated", "format": "PERCENTAGE" }, { "name": "roas", "label": "ROAS", "type": "calculated", "format": "FLOAT" }, { "name": "purchaseCostPer", "label": "Cost Per Purchase", "type": "calculated", "format": "MONEY" }, { "name": "costPerResult", "label": "Cost Per Result", "type": "calculated", "format": "MONEY" } ] } ``` ## Daily Ad Spend Get daily ad spend per account across all connected platforms. Useful for balance management and budget monitoring. Supports Facebook/Meta (via BigQuery + Graph API fallback), TikTok, Pinterest, Snapchat, and Google Ads. ### GET /v1/spend/daily Returns daily spend broken down by ad account. Query parameters: | Param | Required | Description | |-------|----------|-------------| | startDate | yes | Start date (YYYY-MM-DD) | | endDate | yes | End date (YYYY-MM-DD) | | accountIds | no | Comma-separated ad account IDs to filter (defaults to all accounts) | | workspaceId | no | Filter to a specific workspace | | platform | no | Filter by platform: "facebook", "tiktok", "pinterest", "snapchat", "google_ads", "axon" (AppLovin) | Date range is capped at 90 days per request. AppLovin (axon) accounts are fetched live from AppLovin's Reporting API, need the account's Reporting API Key connected in Integrations → AppLovin, and only cover the most recent 45 days (wider windows are clamped). ```bash curl -sS "https://api.admanage.ai/v1/spend/daily?startDate=2026-03-01&endDate=2026-03-09" \ -H "Authorization: Bearer " ``` Example with filters: ```bash curl -sS "https://api.admanage.ai/v1/spend/daily?startDate=2026-03-01&endDate=2026-03-09&accountIds=act_384730851257635&platform=facebook" \ -H "Authorization: Bearer " ``` Response: ```json { "success": true, "data": [ { "date": "2026-03-01", "accountId": "act_384730851257635", "accountName": "Admanage Limited", "platform": "facebook", "currency": "USD", "spend": 150.42 }, { "date": "2026-03-01", "accountId": "7486153503963054097", "accountName": "TikTok Main Account", "platform": "tiktok", "currency": "USD", "spend": 75.00 } ], "metadata": { "startDate": "2026-03-01", "endDate": "2026-03-09", "accountCount": 2, "totalSpend": 367.60, "platforms": ["facebook", "tiktok"], "lastSyncedAt": "2026-03-09T10:11:48.000Z" } } ``` Data freshness: - `metadata.lastSyncedAt` is when AdManage's warehouse data (Meta) was last synced from the platform (ISO 8601). Null when every returned row was fetched live from a platform API. - Meta figures reflect the account state at `lastSyncedAt`: a day that was still in progress at that time (or synced before Meta finished settling it — up to 48h after day-end UTC) may still increase on a later sync. - For automated reporting on previous-day Meta spend, check that `lastSyncedAt` is comfortably after the day ended (ideally 48h) before publishing. If a platform fails (e.g. token expired), partial results are returned with an errors array: ```json { "success": true, "data": [...], "metadata": {...}, "errors": [ { "platform": "tiktok", "message": "TikTok not connected" } ] } ``` **Diagnostics (warnings):** When no accounts match, the response includes a top-level `warnings` array explaining why: ```json { "success": true, "data": [], "metadata": { "startDate": "2026-03-01", "endDate": "2026-03-09", "accountCount": 0, "totalSpend": 0, "platforms": [] }, "warnings": [ "None of the requested account IDs (act_999) were found for this API key. Verify the account IDs are correct and connected in AdManage settings." ] } ``` ## Comments Retrieve and manage ad comments. Comments are collected in real-time from Facebook/Meta via webhook subscriptions, with AI-powered sentiment analysis (1-100 scale). Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive. ### GET /v1/comments List comments with filtering and pagination. Query parameters: | Param | Required | Description | |-------|----------|-------------| | page | no | Page number (default 1) | | limit | no | Results per page, max 100 (default 25) | | accountId | no | Filter by ad account ID, e.g. act_123 (also accepts adAccountId). Must be an account your company owns; any other id returns 403. Omit to cover every account you own | | adId | no | Filter by specific ad ID | | sentiment | no | Filter: "positive" (67-100), "neutral" (34-66), "negative" (1-33) | | hidden | no | Filter by hidden status: "true" or "false" | | startDate | no | Start date (YYYY-MM-DD) | | endDate | no | End date (YYYY-MM-DD) | | search | no | Search in comment text, author name, or ad name (case-insensitive) | | sortBy | no | Sort field: "commentDate", "likes", "sentiment", "lastUpdated" (default: commentDate) | | sortDirection | no | "ASC" or "DESC" (default: DESC) | ```bash curl -sS "https://api.admanage.ai/v1/comments?page=1&limit=25&accountId=act_123&sentiment=negative" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 4554179, "commentId": "1542661021111818_1245574530890886", "text": "Great product, love it!", "author": "John Doe", "authorId": "26271573105814472", "date": "2026-03-10T14:30:00.000Z", "likes": 5, "replyCount": 2, "sentiment": 85, "sentimentLabel": "positive", "hidden": false, "adId": "120248289622780456", "adName": "Spring Sale - UGC", "accountId": "act_123456789", "permalink": "https://www.facebook.com/...", "companyReply": null, "companyReplyTime": null, "reply": null, "spend": null, "impressions": null, "analysis": null } ], "pagination": { "page": 1, "limit": 25, "total": 39562, "totalPages": 1583 } } ``` ### GET /v1/comments/analytics Get aggregated comment analytics: sentiment distribution, top ads by comment count, and daily volume over time. Query parameters: | Param | Required | Description | |-------|----------|-------------| | accountId | no | Filter by ad account ID, e.g. act_123 (also accepts adAccountId). Must be an account your company owns; any other id returns 403. Omit to cover every account you own | | startDate | no | Start date (YYYY-MM-DD) | | endDate | no | End date (YYYY-MM-DD) | If no date range is provided, volumeOverTime defaults to the last 30 days. ```bash curl -sS "https://api.admanage.ai/v1/comments/analytics?accountId=act_123&startDate=2026-03-01&endDate=2026-03-31" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "summary": { "totalComments": 24347, "avgSentiment": 42.2, "analyzedComments": 24116, "hiddenComments": 10571, "commentsWithReplies": 749 }, "sentimentDistribution": { "positive": { "count": 5087, "percentage": 21 }, "neutral": { "count": 6800, "percentage": 28 }, "negative": { "count": 12229, "percentage": 51 } }, "topAds": [ { "adId": "120248289622780456", "adName": "Spring Sale - UGC", "commentCount": 85, "avgSentiment": 72.5, "totalLikes": 230 } ], "volumeOverTime": [ { "date": "2026-03-01T00:00:00.000Z", "count": 701 }, { "date": "2026-03-02T00:00:00.000Z", "count": 626 } ] } } ``` ## Launch Drafts Save, iterate, and launch ad drafts via the API. Ad account ownership is validated on create (POST /v1/drafts), on update (PATCH /v1/drafts/{id}), and again at launch (POST /v1/drafts/{id}/launch). Every `businessId` / `adAccountId` / `accountIds` / `accountAssignments` value must be an account returned by GET /v1/adaccounts, matched with or without the `act_` prefix; anything else is rejected with 400 `ad_account_not_authorized` and nothing is saved or launched. See "Launch errors" under Launch. - POST /v1/drafts Body: { title, businessId (required), workspaceId, status, state } ```bash curl -sS -X POST "https://api.admanage.ai/v1/drafts" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"title":"My Draft","businessId":"act_123","state":{"globalDefaults":{"title":"Spring Sale"},"rows":[]}}' ``` Response (201): ```json { "success": true, "draftId": 42, "draftUrl": "https://admanage.ai/ingestDraft?draftId=42&businessId=act_123", "viewDraftPath": "/ingestDraft?draftId=42&businessId=act_123", "data": { "id": 42, "title": "My Draft", "businessId": "act_123", "workspaceId": null, "status": "draft", "user": "user@acme.com", "company": "acme", "createdAt": "2026-02-19T10:00:00.000Z", "state": { "globalDefaults": { "title": "Spring Sale" }, "rows": [] } } } ``` **Google Ads drafts.** `POST /v1/drafts` with `"platform": "google_ads"` takes the same body as `POST /v1/google-ads/launch` (`accountId` required) and saves it instead of launching. Nothing is sent to Google Ads. The response carries `draftId` and `draftUrl`: opening the URL shows the draft in the AdManage Google Ads editor with its campaign, ad groups, ads and staged assets selected, ready to review and launch. `POST /v1/drafts/{id}/launch` launches it with the stored body and returns `adBatchId` (poll it like any Google Ads batch). Only drafts created this way launch through the API; a Google Ads draft saved in AdManage or from Sheets is launched from AdManage. ```bash curl -sS -X POST "https://api.admanage.ai/v1/drafts" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"platform":"google_ads","title":"Android FR - new videos","accountId":"1234567890","campaignId":"22334455667","adGroupIds":["11122233344"],"selectedAdIds":["99988877766"],"videos":[{"youtubeVideoId":"dQw4w9WgXcQ"}]}' ``` Simplified draft body: `POST /v1/drafts` also accepts `{ title, ads }` with the same ad shape as `POST /v1/launch`. For Meta Instagram post boosts, pass `instagramPostUrl` or `instagramPostUrls`; AdManage resolves the organic post and creates one draft row per URL. For an existing TikTok Upgraded Smart+ ad group, pass the saved ad group object from `GET /v1/adsets?platform=tiktok&accountId=` in `ads[].adSets[]`. A bare ad group ID also works: draft creation reads TikTok's current ad group family and stores it on the selection. A supplied `campaign_automation_type` must match that live read or the draft is rejected. `isSmartPlus` is optional and only checks consistency; it does not select the launch path. If TikTok cannot verify the group, the draft is not saved. The account must belong to the API key's company/workspace. Spark ads in simplified `{ ads }` requests are single-account: do not pass `accountIds` or `accountAssignments`; create a separate verified request for each TikTok advertiser. The same family check applies to direct simplified `POST /v1/launch` calls. Raw `{ state }` drafts and raw `{ creativeState }` launches do not receive this provider-family verification. The Spark post must already be authorized for that advertiser and identity; the simplified API validates request shape, account ownership and ad group family, while TikTok's post/creative acceptance is checked at launch. Example: save a PAUSED Spark post draft in an existing Upgraded Smart+ ad group. Supply a real authorized `itemId`, `identityId`, and `identityType` for your advertiser; the IDs below are illustrative. ```bash curl -sS -X POST "https://api.admanage.ai/v1/drafts" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"title":"TikTok Spark creative test","ads":[{"platform":"tiktok","adAccountId":"7486153503963054097","adSets":[{"value":"1859479128199217","label":"Existing Smart+ app group","account_id":"7486153503963054097","campaign_automation_type":"UPGRADED_SMART_PLUS"}],"tiktokPost":{"itemId":"7519200000000000001","identityId":"creator-identity-from-TikTok","identityType":"AUTH_CODE","caption":"Creator post"},"adName":"Spark winner","title":"Creator post","cta":"LEARN_MORE","launchPaused":true}]}' ``` Saving the draft creates no TikTok ad. Review it, then call `POST /v1/drafts/{id}/launch` to create the ad; keep `launchPaused: true` for a non-delivering first test. The Spark identity and post are still subject to TikTok's permissions and APP_PROMOTION creative rules. Do not infer provider acceptance from a successful draft save. ```bash curl -sS -X POST "https://api.admanage.ai/v1/drafts" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "title": "IG post boost draft", "ads": [ { "adName": "Boost IG reel draft", "adAccountId": "act_384730851257635", "workspaceId": "workspace_abc", "instagramPostUrl": "https://www.instagram.com/reel/BoostMe_123/", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "page": "470703006115773", "insta": "17841471826052348", "adSets": [ { "value": "120248289622780456", "label": "US Broad 25-44" } ] } ] }' ``` - GET /v1/drafts Query: page, limit, businessId, workspaceId, search ```bash curl -sS "https://api.admanage.ai/v1/drafts?page=1&limit=25&businessId=act_123" \ -H "Authorization: Bearer " ``` ```json { "data": [ { "id": 42, "title": "My Draft", "businessId": "act_123", "workspaceId": null, "status": "draft", "user": "user@acme.com", "company": "acme", "createdAt": "2026-02-19T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 } } ``` - GET /v1/drafts/:id ```bash curl -sS "https://api.admanage.ai/v1/drafts/42" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "id": 42, "title": "My Draft", "businessId": "act_123", "status": "draft", "state": { "globalDefaults": { "title": "Spring Sale" }, "rows": [] }, "createdAt": "2026-02-19T10:00:00.000Z" } } ``` - PATCH /v1/drafts/:id Body: { title?, businessId?, workspaceId?, status?, state? } ```bash curl -sS -X PATCH "https://api.admanage.ai/v1/drafts/42" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"title":"Updated Draft","state":{"globalDefaults":{"title":"Summer Sale"},"rows":[{"id":"row-1"}]}}' ``` ```json { "success": true, "data": { "id": 42, "title": "Updated Draft", "status": "draft", "state": { "globalDefaults": { "title": "Summer Sale" }, "rows": [{ "id": "row-1" }] } } } ``` - DELETE /v1/drafts/:id ```bash curl -sS -X DELETE "https://api.admanage.ai/v1/drafts/42" \ -H "Authorization: Bearer " ``` ```json { "success": true, "message": "Draft deleted" } ``` - POST /v1/drafts/:id/launch ```bash curl -sS -X POST "https://api.admanage.ai/v1/drafts/42/launch" \ -H "Authorization: Bearer " ``` Response (202): ```json { "success": true, "message": "Ad launch initiated successfully", "adBatchSlug": "a1b2c3d4", "adBatchId": 9913, "isAsync": true } ``` Ad accounts are re-validated at launch time, not just when the draft was saved. If the draft's ad account has since been disconnected (or was never yours), the launch is rejected with 400 `ad_account_not_authorized`, no batch is created, and the draft stays in `draft` status. **Multi-account drafts.** Per-row ad accounts work here: a draft whose rows each carry their own `adAccountId` on a single platform dispatches the same single, per-row-routed batch as POST /v1/launch. Nothing anywhere splits a launch per ad account. Two fan-outs are NOT applied by this endpoint: (1) rows carrying `accountAssignments` are never expanded, so only each row's primary account launches and the remaining assignments are silently dropped; (2) rows spanning several platforms are never split per platform, so they are dispatched as one batch to a single launcher and the other platforms' rows fail there. Use POST /v1/launch for either case — it runs both expansions before dispatch. ## Media Library Browse, search, and filter creative assets in your media library. - GET /v1/library/assets Assets include nullable `timelinerTaskId` and `timelinerFileId` beside `source`. These identify the task and original file captured at import, independently of later file versions. Older Timeliner imports return the file ID from their saved source identity and a null task ID until reimported with task metadata. Non-Timeliner assets return null for both. The same fields are returned by asset detail and board asset endpoints. Query: search, filterType (all|image|video|gif), sortBy (dateCreated|dateModified|name|size), sortOrder (asc|desc), boardId, creativeStatus (raw|in_progress|approved|archived), launchStatus (Launched|Not Launched), launchChannels (comma-sep: meta,tiktok,snapchat,pinterest,axon,google_ads,moloco,unity), tags (comma-sep), dimension (1080x1920 or 9:16), uploader (email), limit (max 100), cursor ```bash curl -sS "https://api.admanage.ai/v1/library/assets?limit=10&filterType=video&sortBy=dateCreated&sortOrder=desc" \ -H "Authorization: Bearer " ``` ```json { "assets": [ { "id": 12345, "adid": 67890, "name": "Spring-UGC.mp4", "url": "https://media.admanage.ai/acme/Spring-UGC.mp4", "thumbnail": "https://media.admanage.ai/acme/thumb-Spring-UGC.jpg", "mimeType": "video/mp4", "size": 15728640, "dimension": "1080x1920", "type": "video", "dateAdded": "2026-02-18T08:25:12.000Z", "lastUpdated": "2026-02-18T10:00:00.000Z", "uploaderStatus": "approved", "status": "Launched", "launchChannels": [ { "platform": "meta", "adIds": ["120012345678901234"] } ], "tags": [{ "id": 1, "name": "UGC" }], "boardIds": [10, 22] } ], "nextCursor": "12344", "hasMore": true, "total": 847 } ``` - GET /v1/library/assets/:id ```bash curl -sS "https://api.admanage.ai/v1/library/assets/12345" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "id": 12345, "name": "Spring-UGC.mp4", "url": "https://media.admanage.ai/acme/Spring-UGC.mp4", "type": "video", "transcript": "Hey guys, check out this amazing product...", "smartSummary": "UGC testimonial video featuring product demo", "smartTags": ["ugc", "testimonial", "product-demo"], "launchChannels": [ { "platform": "meta", "adIds": ["120012345678901234"] } ] } } ``` - GET /v1/library/boards ```bash curl -sS "https://api.admanage.ai/v1/library/boards" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 10, "name": "Q1 Creatives", "visibility": "team", "assetCount": 42, "children": [ { "id": 11, "name": "UGC", "assetCount": 18, "children": [] } ] } ] } ``` - GET /v1/library/boards/:id/assets Same query params and response shape as GET /v1/library/assets, scoped to a specific board. ```bash curl -sS "https://api.admanage.ai/v1/library/boards/10/assets?limit=25" \ -H "Authorization: Bearer " ``` - GET /v1/library/tags ```bash curl -sS "https://api.admanage.ai/v1/library/tags" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 1, "name": "UGC", "company": "acme" }, { "id": 2, "name": "Product Demo", "company": "acme" } ] } ``` ## X (Twitter) Ads X accounts are connected in Settings > Integrations > X and appear in GET /v1/adaccounts with type "x" (ids are bare base36 strings such as "18ce54d4x5t"). X is NOT served by POST /v1/launch or /v1/reports/query — use the dedicated routes below. All routes need the API key's workspace; xAccountId must be an X account in that workspace. If X rejects the stored OAuth token the API returns 401 with "Reconnect X Ads". Launch — POST /v1/x-ads/launch (read_write key): ```json { "accountId": "18ce54d4x5t", "campaignName": "Autumn promo", "adGroupName": "Autumn promo - Ad group", "objective": "WEBSITE_CLICKS", "placements": ["ALL_ON_TWITTER"], "dailyBudgetAmountLocalMicro": 50000000, "bidAmountLocalMicro": 1500000, "launchPaused": true, "ads": [ { "postText": "New season, new gear.", "mediaUrls": ["https://media.admanage.ai/acme/autumn.mp4"], "websiteUrl": "https://acme.com/autumn" } ] } ``` - objective: "ENGAGEMENTS" (default), "WEBSITE_CLICKS", "VIDEO_VIEWS", or "REACH". placements: "ALL_ON_TWITTER" (default) and/or "PUBLISHER_NETWORK". - Budgets/bids are micro units of the account currency (1 USD = 1000000). launchPaused defaults to true. - Each ads[] entry becomes one post (max 280 chars, up to 4 mediaUrls — images or MP4 video) promoted under the line item. A legacy body with a single "postText" instead of ads[] is still accepted. - Existing ad groups: pass "lineItemIds": ["", ...] (ids from GET /v1/x-ads/ad-groups) instead of campaignName/adGroupName/budget/bid. No campaign or line item is created; each line item must belong to accountId (else 400) and every ad is promoted into every listed line item (one post per ad, reused across line items). - Response: { batchId, campaign: { id, name, entity_status }, lineItem, lineItems: [{ id, name, campaign_id, entity_status, objective? }], ads: [{ postText, tweetId, promotedPostIds: [...], promotedPostId, error? }], currency }. lineItem is lineItems[0]; promotedPostId is promotedPostIds[0]. The batch shows in GET /v1/adbatches with channel "x" (adSetIds = comma-joined line item ids). Manage — lists (GET, query params xAccountId, search, page, pageSize, campaignIds, adGroupIds, startDate, endDate; metrics default to the last 30 days): - GET /v1/x-ads/campaigns → rows { campaignId, campaignName, status, servable, dailyBudgetMicro, totalBudgetMicro, currency, startTime, endTime, createdTime, metrics } - GET /v1/x-ads/ad-groups → rows { adGroupId, adGroupName, campaignId, campaignName, campaignStatus, status, servable, objective, productType, placements, bidMicro, dailyBudgetMicro (campaign), currency, startTime, endTime, createdTime, metrics }. Add includeMetrics=false to skip stats (metrics zeroed) when only picking targets for a launch. - GET /v1/x-ads/ads → rows { adId, adName, tweetId, adGroupId, adGroupName, campaignId, campaignName, status, approvalStatus, text, thumbnail, mediaType, createdTime, metrics } - metrics: { impressions, engagements, clicks, urlClicks, spend, videoViews, ctr, cpc, cpm } (spend in local currency, both X placements summed) - Response shape: { success, data, totalCount, page, pageSize } Manage — mutations (POST, read_write key, body always includes xAccountId): - /v1/x-ads/update-status { entityType: "campaigns"|"adgroups"|"ads", entityId, newStatus: "ACTIVE"|"PAUSED" } - /v1/x-ads/update-name { entityType: "campaigns"|"adgroups", entityId, newName } (1–255 chars; promoted posts cannot be renamed) - /v1/x-ads/update-budget { entityType: "campaigns", entityId, dailyBudget?, totalBudget? } or { entityType: "adgroups", entityId, bid? } — local currency units, converted to micro - /v1/x-ads/delete { entityType, entityIds: [...] } (max 100) → { success, successIds, failures: [{ entityId, error }] } Manage — create / duplicate (POST, read_write key, body always includes xAccountId; money in local currency units, converted to micro; launchPaused defaults to true): - /v1/x-ads/create-campaign { name, dailyBudget, totalBudget?, launchPaused? } → { success, campaign: { campaignId, campaignName, status, dailyBudgetMicro, totalBudgetMicro, currency, ... } } (uses the account's active funding instrument). Add adGroup: { name, objective, bidStrategy?, bid?, placements?, iosAppStoreIdentifier?, androidAppStoreIdentifier? } to also create the first ad group → { success, campaign, adGroups } (the campaign is removed if the ad group fails) - /v1/x-ads/create-ad-group { campaignId, name, objective: "ENGAGEMENTS"|"WEBSITE_CLICKS"|"VIDEO_VIEWS"|"REACH"|"APP_INSTALLS", placements?: ["ALL_ON_TWITTER"|"PUBLISHER_NETWORK"], bid?, bidStrategy?: "AUTO"|"MAX"|"TARGET", dailyBudget?, iosAppStoreIdentifier?, androidAppStoreIdentifier?, launchPaused?, startTime?: ISO } → { success, adGroup: ad-groups row } (PROMOTED_TWEETS line item; startTime defaults to now + 5 min) - /v1/x-ads/duplicate-campaign { campaignId, name?, includeAdGroups?, launchPaused? } → { success, campaign, adGroups: [ad-groups rows] } (name defaults to " - Copy"; copies every non-deleted line item unless includeAdGroups is false) - /v1/x-ads/duplicate-ad-group { adGroupId, name?, campaignId?, launchPaused? } → { success, adGroup } (copies into the source campaign unless campaignId is given) Import from Meta (POST, read_write key) — turn Meta ads into X promoted posts in two steps: - /v1/x-ads/import/resolve { metaAccountId, campaignId?, adIds?, xAccountId, destination?: { lineItemIds? } | { campaignName, adGroupName, objective?, placements?, dailyBudgetAmountLocalMicro?, bidAmountLocalMicro? }, mappingOptions?: { carryUrlTags?: boolean, launchPaused?: boolean } } → { success, launchBody, ads: [{ adId, adName, postText, websiteUrl, mediaUrls, mediaType, thumbnailUrl }], skipped: [{ adId, name, reason }], warnings: [{ adId, field, message }], compatibility }. Nothing is created. Mapping: primary text → post text (280-char cap, headline fallback), first image/video → media (carousel/collection: first card, with a warning), Meta objective → X objective (traffic → WEBSITE_CLICKS, engagement → ENGAGEMENTS, video/awareness → VIDEO_VIEWS or REACH, else ENGAGEMENTS); the link is attached only for WEBSITE_CLICKS. Targeting, pixels, CTAs and headlines have no X equivalent and are reported in compatibility, not carried over. Dynamic/catalog ads are skipped. - /v1/x-ads/import/launch { xAccountId, ...launchBody } — send the resolved launchBody back (edit ads[] / destination fields first if needed) → same response as /v1/x-ads/launch. Stats — GET /v1/x-ads/stats?xAccountId=...&entity=PROMOTED_TWEET&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD → { success, rows } (every entity with metrics for the range; entity may also be LINE_ITEM or CAMPAIGN). Top ads (GET /v1/analytics/top-ads) route X accounts here automatically. ## Manage (Mintegral) Mintegral uses a three-level hierarchy: campaign = promoted app/website, offer = delivery settings, creative set = bound uploaded creatives and output formats. - GET|POST|PUT /v1/manage/mintegral/campaigns - POST /v1/manage/mintegral/campaigns/duplicate - GET|POST|PUT /v1/manage/mintegral/offers - POST /v1/manage/mintegral/offers/duplicate - POST /v1/manage/mintegral/offers/update-status - POST /v1/manage/mintegral/offers/update-budget - POST /v1/manage/mintegral/offers/update-bids - GET|POST|PUT|DELETE /v1/manage/mintegral/creative-sets - POST /v1/manage/mintegral/creative-sets/duplicate All requests require accountId (the connected mintegral_* account) and workspaceId unless the API key already supplies a default workspace. Offer create and duplicate operations default to STOPPED. Set RUNNING only when real delivery should begin. Campaign duplicate body: ```json { "accountId": "mintegral_106572", "workspaceId": "workspace_abc", "campaignId": "1234", "newName": "My App Copy", "copyCount": 1, "includeOffers": true, "includeCreativeSets": true, "offerInitialStatus": "STOPPED" } ``` Create offer body: ```json { "accountId": "mintegral_106572", "workspaceId": "workspace_abc", "campaignId": "1234", "offerName": "US_CPI_Test", "promoteTimezone": 0, "startTime": 1800000000, "targetGeo": "US", "billingType": "CPI", "bidRate": 1.25, "targetAdType": "REWARDED_VIDEO", "initialStatus": "STOPPED" } ``` Direct creative-set creation uses Mintegral creative MD5s. To upload public URL/local media and create sets through createAdBatch, use POST /v1/launch with platform:"mintegral". ## Manage (Moloco) Moloco hierarchy: ad account → product (promoted app) → campaign → ad group → creative group → creative. Connect accounts in AdManage → Integrations → Moloco (API key); connected accounts use the moloco_ id. - GET /v1/manage/moloco/campaigns?accountId= — campaigns with nested ad groups, budget (dailyBudget or weeklyBudget; the other is null), goal (goalType, goalMode), bidAmount (the editable target CPI/CPC/CPM bid, else null), targetRoas (ROAS goals, percent), and per-ad-group creative review counts - GET /v1/manage/moloco/ad-groups?accountId=&campaignId= — flat launch targets, exactly the molocoAdGroups shape for POST /v1/launch - GET /v1/manage/moloco/performance?accountId=&level=campaign|ad_group|creative&startDate=&endDate=&limit= — spend, impressions, clicks, installs, CTR, CPI from Moloco's async report API (level=creative = top creatives; defaults to the last 7 days) - PUT /v1/manage/moloco/campaigns — { accountId, campaignId, enabled?, name?, dailyBudget?, weeklyBudget?, bidAmount?, targetRoas? }. Send the budget field the campaign uses; bidAmount / targetRoas (percent, 150 = 150%) only where the list shows a non-null value — budget-centric goals and CPA goals have no bid Moloco would use, so those edits get a 400 and nothing changes. The campaign is read back after saving: { verified, changes: [{ field, before, after }] }; 409 moloco_edit_not_applied = Moloco accepted the request but did not keep a value (the message names it). - PUT /v1/manage/moloco/ad-groups — { accountId, campaignId, adGroupId, enabled?, name? } All requests require accountId and workspaceId unless the API key already supplies a default workspace. To push new creatives, use POST /v1/launch with platform:"moloco" and molocoAdGroups; the batch message reports creative groups still in Moloco review. ## Manage (Create) Create new Meta campaigns and ad sets from scratch. These endpoints now mirror the richer /manage create flow, including CBO budgets, promoted objects, app-promotion bindings, website lead setups, value rules, schedules, and advanced destination settings. - POST /v1/manage/create-campaign Create a new Meta campaign. Body: - Required: { accountId, name, objective } - Common: { status? ("ACTIVE"|"PAUSED"), buyingType? ("AUCTION"|"RESERVED"), specialAdCategories? ([] | ["EMPLOYMENT"|"HOUSING"|"FINANCIAL_PRODUCTS_SERVICES"|"CREDIT"|"ISSUES_ELECTIONS_POLITICS"]), workspaceId? } - Campaign-budget optimization (CBO): { dailyBudget? | lifetimeBudget? } in account currency dollars - Advanced /manage parity fields: { campaignSpendCap?, campaignBudgetType? ("daily"|"lifetime"), campaignBudgetOptimization?, isAdvantagePlusCampaign?, bidStrategy?, campaignBidAmount?, isSkadnetworkAttribution?, promotedObject? } Objectives: - OUTCOME_TRAFFIC - OUTCOME_ENGAGEMENT - OUTCOME_LEADS - OUTCOME_AWARENESS - OUTCOME_SALES - OUTCOME_APP_PROMOTION Campaign promotedObject: - Sales catalog ads: { "product_catalog_id": "..." } - App promotion / SKAdNetwork: { "application_id": "...", "object_store_url": "..." } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/create-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "accountId":"act_123", "name":"Q2 Prospecting", "objective":"OUTCOME_SALES", "status":"PAUSED", "dailyBudget":100, "bidStrategy":"COST_CAP", "campaignBidAmount":35, "promotedObject":{"product_catalog_id":"9988776655"} }' ``` ```json { "success": true, "campaignId": "120248400000000001", "name": "Q2 Prospecting", "objective": "OUTCOME_SALES", "status": "PAUSED", "accountId": "act_123" } ``` More sales campaign examples: Standard website sales campaign: ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/create-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "accountId":"act_123", "name":"Website Sales", "objective":"OUTCOME_SALES", "status":"PAUSED", "dailyBudget":150, "bidStrategy":"LOWEST_COST_WITHOUT_CAP" }' ``` Advantage+ catalog sales campaign: ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/create-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "accountId":"act_123", "name":"Catalog Sales", "objective":"OUTCOME_SALES", "status":"PAUSED", "dailyBudget":300, "campaignBudgetOptimization":true, "isAdvantagePlusCampaign":true, "promotedObject":{"product_catalog_id":"9988776655"} }' ``` - POST /v1/manage/create-adset Create a new Meta ad set inside an existing campaign. Body: - Required: { accountId, campaignId (or campaign_id), name } - Common: { status?, optimizationGoal? (or optimization_goal), billingEvent? (or billing_event), bidStrategy?, bidAmount?, dailyBudget? | lifetimeBudget?, startTime?, endTime?, targeting?, promotedObject?, destinationType?, workspaceId? } - Attribution: attributionSpec? or incrementalAttributionEnabled? (Meta incremental attribution; website conversion ad sets optimizing for OFFSITE_CONVERSIONS/VALUE only, else 400). When both are omitted the ad account's saved default (PATCH /v1/launch-defaults defaultAttributionWindow / incrementalAttribution) is applied. - Advanced /manage parity fields: { attributionSpec?, dsaBeneficiary?, dsaPayor?, dailySpendCap?, lifetimeSpendCap?, valueRuleSetId?, valueRulesApplied?, placementSoftOptOut?, pacingType?, adsetSchedule?, budgetSchedules? } If optimizationGoal is omitted, the API infers the default from the campaign objective: - OUTCOME_TRAFFIC → LANDING_PAGE_VIEWS - OUTCOME_ENGAGEMENT / MESSAGES → CONVERSATIONS - POST_ENGAGEMENT → POST_ENGAGEMENT - OUTCOME_LEADS → LEAD_GENERATION - OUTCOME_AWARENESS → REACH - OUTCOME_SALES → OFFSITE_CONVERSIONS - OUTCOME_APP_PROMOTION → APP_INSTALLS Common destination types: - WEBSITE - APP - MESSENGER - WHATSAPP - INSTAGRAM_DIRECT - ON_AD - WEBSITE_AND_PHONE_CALL Promoted object examples: - Website conversions / sales: { "pixel_id": "123", "custom_event_type": "PURCHASE" } - Website leads with datasets: { "offline_conversion_data_set_id": "123", "custom_event_type": "LEAD" } - Instant-form leads / awareness / engagement: { "page_id": "123" } - App promotion: { "application_id": "123", "object_store_url": "https://apps.apple.com/app/id123" } - Sales messaging destinations: { "page_id": "123" } Sales-focused ad set examples: - Website purchases: { "optimizationGoal":"OFFSITE_CONVERSIONS", "destinationType":"WEBSITE", "promotedObject":{"pixel_id":"123","custom_event_type":"PURCHASE"} } - Website value / ROAS: { "optimizationGoal":"VALUE", "destinationType":"WEBSITE", "promotedObject":{"pixel_id":"123","custom_event_type":"PURCHASE"} } - Website and calls: { "optimizationGoal":"OFFSITE_CONVERSIONS", "destinationType":"WEBSITE_AND_PHONE_CALL", "promotedObject":{"pixel_id":"123","custom_event_type":"PURCHASE"} } - Messaging destinations (combined Instagram Direct + Messenger + WhatsApp): { "optimizationGoal":"OFFSITE_CONVERSIONS", "destinationType":"MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP", "promotedObject":{"page_id":"123"} } - WhatsApp only (engagement): { "optimizationGoal":"CONVERSATIONS", "billingEvent":"IMPRESSIONS", "destinationType":"WHATSAPP", "promotedObject":{"page_id":"123","whatsapp_phone_number":"+85212345678"} } (full recipe: "Recipe — paused WhatsApp-only hierarchy" below) - Calls only: { "optimizationGoal":"OFFSITE_CONVERSIONS", "destinationType":"PHONE_CALL" } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/create-adset" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "accountId":"act_123", "campaignId":"120248400000000001", "name":"US Broad 25-54", "optimizationGoal":"OFFSITE_CONVERSIONS", "dailyBudget":50, "bidStrategy":"COST_CAP", "bidAmount":20, "targeting":{ "geo_locations":{"countries":["US"]}, "age_min":25, "age_max":54, "genders":[1,2] }, "promotedObject":{"pixel_id":"123456","custom_event_type":"PURCHASE"}, "attributionSpec":[{"event_type":"CLICK_THROUGH","window_days":7}], "valueRuleSetId":"120200000000000001", "valueRulesApplied":true }' ``` ```json { "success": true, "adSetId": "120248400000000002", "name": "US Broad 25-54", "campaignId": "120248400000000001", "status": "PAUSED", "accountId": "act_123", "optimizationGoal": "OFFSITE_CONVERSIONS", "billingEvent": "IMPRESSIONS", "destinationType": "WEBSITE", "promotedObject": {"pixel_id":"123456","custom_event_type":"PURCHASE"} } ``` The response echoes the goal, billing event, destination and promoted object sent to Meta. `warnings` lists every change AdManage made to your request (billing event auto-corrected, default goal, account attribution/language defaults, targeting fields Meta rejected and AdManage removed, advantage_audience Meta required). No warnings = Meta received exactly what you sent. To confirm what Meta stored, read it back with POST /v1/manage/meta-entity-settings. ## Manage (Read back) — effective Meta settings - POST /v1/manage/meta-entity-settings (read key) Live read from Meta of campaigns, ad sets, ads and creatives, each level independently. Body: { entities: [{ level: "campaign"|"adset"|"ad"|"creative", id: "", accountId? }] (1-50), accountId?, workspaceId? } When accountId is given (per entity or top level), an entity owned by another ad account fails with an error instead of being returned. Each data[] item has success plus, per level: - campaign: status, effectiveStatus, configuredStatus, objective, buyingType, bidStrategy, budget, specialAdCategories - adset: campaignId, status, effectiveStatus, configuredStatus, destinationType, optimizationGoal, billingEvent, bidStrategy, bidAmount, promotedObject, targeting, attributionSpec, budget, startTime, endTime - ad: campaignId, adSetId, status, effectiveStatus, configuredStatus, creativeId - creative: status, objectType, pageId, callToAction { type, appDestination }, pageWelcomeMessage, usesAssetFeed - raw: the Meta Graph fields as returned budget = { dailyBudget, lifetimeBudget, budgetRemaining, units: "minor" } — Meta's account-currency minor units (cents for 2-decimal currencies: 5000 = 50.00). create-campaign / create-adset dailyBudget is in MAJOR units (50 = 50.00); send daily_budget there for minor units. ## Recipe — paused WhatsApp-only (click-to-WhatsApp) hierarchy Creation order: campaign → ad set → ad (the creative is created with the ad). All three are created PAUSED below. 1. Campaign (status defaults to PAUSED): POST /v1/manage/create-campaign { "accountId":"act_123", "name":"WA enquiries HK/MY", "objective":"OUTCOME_ENGAGEMENT", "status":"PAUSED" } Campaign budget (CBO) is optional: dailyBudget (major units). Omit it to budget on the ad set. 2. Ad set (status defaults to PAUSED): POST /v1/manage/create-adset { "accountId":"act_123", "campaignId":"", "name":"WA HK+MY", "status":"PAUSED", "destinationType":"WHATSAPP", "optimizationGoal":"CONVERSATIONS", "billingEvent":"IMPRESSIONS", "promotedObject":{"page_id":"","whatsapp_phone_number":""}, "targeting":{"geo_locations":{"countries":["HK","MY"]}}, "dailyBudget":50 } - destinationType is sent to Meta exactly as given. WHATSAPP is WhatsApp-only; AdManage never substitutes a combined messaging destination (MESSAGING_MESSENGER_WHATSAPP, MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP, ...). Use those values only when you want combined destinations. - promotedObject.page_id is required (400 without it). whatsapp_phone_number is optional; without it Meta uses the number linked to the Page and the response carries a warning. - billing_event for CONVERSATIONS is IMPRESSIONS; another value is auto-corrected and reported in warnings. 3. Ad (+ creative): POST /v1/launch with launchPaused: true. Ads launch ACTIVE unless launchPaused is true. { "launchPaused": true, "ads":[{ "adAccountId":"act_123", "page":"", "adSets":[{"value":"","label":"WA HK+MY"}], "adName":"WA enquiry 1", "body":"Chat with us on WhatsApp", "title":"Message us", "media":[{"url":"https://.../image.jpg","type":"image"}], "pageWelcomeMessage":{"mode":"icebreakers","greetingText":"Hi! How can we help?","icebreakerTitles":["Prices","Opening hours"]} }] } - The creative inherits the WhatsApp destination from the ad set: its CTA is always WHATSAPP_MESSAGE with app_destination WHATSAPP (Meta rejects other CTAs on click-to-WhatsApp ads, so any other cta you send is replaced). - pageWelcomeMessage is optional (top level or per ad): mode "default" | "autofill" | "icebreakers" | "call_prompt" | "flow", with greetingText, autofillContent, icebreakerTitles, callPromptMessage, flowId, flowCallToAction. 4. Verify each level: POST /v1/manage/meta-entity-settings { "accountId":"act_123", "entities":[ {"level":"campaign","id":""}, {"level":"adset","id":""}, {"level":"ad","id":""}, {"level":"creative","id":""} ] } Expect status PAUSED on campaign / ad set / ad, destinationType WHATSAPP, optimizationGoal CONVERSATIONS, billingEvent IMPRESSIONS, promotedObject with your page_id / whatsapp_phone_number, targeting.geo_locations.countries ["HK","MY"], creative callToAction { type: WHATSAPP_MESSAGE, appDestination: WHATSAPP }. Known Meta constraints: the Page must have a WhatsApp Business number connected; Meta validates objective / goal / destination combinations and its error is returned as a 400. Ad IDs come from GET /v1/batch-status/{adBatchId} (or GET /v1/manage/list-ads for the ad set). ## Manage (Duplicate) Duplicate campaigns, ad sets, and ads on Facebook. - POST /v1/manage/duplicate-adset Duplicate a Facebook ad set (1-10 copies). Uses smartCopy (sync first, async batch fallback for large ad sets). Body: { adSetId (or adsetId), accountId, copyCount (1-10), initialStatus? ("ACTIVE"|"PAUSED"), isAdSetLive? (boolean; initialStatus takes precedence), startDate? (ISO-8601), endDate? (ISO-8601 or empty for ongoing), targetCampaignId?, newName?, deepCopy? (default false), bidAmount? (account-currency dollars), bidStrategy? ("LOWEST_COST_WITHOUT_CAP"|"LOWEST_COST_WITH_BID_CAP"|"COST_CAP"|"TARGET_COST"), workspaceId? } For capped CBO destinations, pass bidAmount; the campaign strategy is inherited and AdManage sends the required ad-set bid amount in Meta minor units with the copy request. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-adset" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"120248289622780456","accountId":"act_123","copyCount":2,"initialStatus":"PAUSED","deepCopy":true}' ``` ```json { "success": true, "originalAdSetId": "120248289622780456", "results": [ { "copyNumber": 1, "success": true, "newAdSetId": "120248289622780457" }, { "copyNumber": 2, "success": true, "newAdSetId": "120248289622780458" } ], "successCount": 2, "failCount": 0 } ``` - POST /v1/manage/duplicate-campaign Duplicate a Meta/Facebook or Taboola campaign (1-10 copies). For Taboola, set platform:"taboola"; includeItems defaults true. Body: { campaignId, accountId, copyCount (1-10), platform? ("facebook"|"meta"|"taboola"), initialStatus? ("ACTIVE"|"PAUSED"), newName?, deepCopy?, copyDepth?, includeItems?, workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"campaignId":"120247699100220456","accountId":"act_123","copyCount":1,"initialStatus":"PAUSED"}' ``` ```json { "success": true, "originalCampaignId": "120247699100220456", "results": [ { "copyNumber": 1, "success": true, "newCampaignId": "120247699100220457" } ], "successCount": 1, "failCount": 0 } ``` Taboola example: ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"platform":"taboola","campaignId":"campaign-123","accountId":"taboolaaccount-cedadmanageai","copyCount":1,"newName":"Taboola Campaign Copy","includeItems":true,"workspaceId":"workspace_abc"}' ``` - POST /v1/manage/pinterest/duplicate-campaign Duplicate a Pinterest campaign by recreating the source hierarchy through Pinterest v5. Copies are paused by default. Body: { accountId, campaignId, newName?, status? ("ACTIVE"|"PAUSED"), duplicateAdGroups?, duplicateAds?, duplicateProductGroupPromotions?, workspaceId? } MCP equivalent: `duplicate_pinterest_campaign`. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/pinterest/duplicate-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"accountId":"549755885175","campaignId":"626736423001","newName":"Pinterest Campaign Copy","status":"PAUSED"}' ``` - POST /v1/manage/tiktok/duplicate-campaign Duplicate a standard or Smart+ TikTok campaign. Synchronous: the response has the new IDs (no operationKey to poll). Copies are PAUSED unless initialStatus is "ACTIVE". Body: { advertiserId, campaignId, newName?, initialStatus? ("ACTIVE"|"PAUSED"), copyDepth? ("campaign" = empty shell, default | "full" = with ad groups and paused ads), workspaceId? } Response: { success, platform: "tiktok", originalCampaignId, newCampaignId, newAdGroupIds } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/tiktok/duplicate-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"advertiserId":"6920267098044235778","campaignId":"1800000000000001","newName":"Creative test W40","copyDepth":"campaign"}' ``` - POST /v1/manage/tiktok/duplicate-adgroup Duplicate a TikTok ad group (targeting, placements, identity, optimization, bidding) into the same or another campaign. Ads are not copied. Synchronous. Body: { advertiserId, adGroupId, targetCampaignId?, newName?, dailyBudget? (major units, e.g. 25), startDate?/endDate? ("YYYY-MM-DDTHH:mm" wall-clock in timezone), timezone? (IANA, e.g. "Europe/Paris"; default UTC), initialStatus? ("ACTIVE"|"PAUSED", default PAUSED), workspaceId? } Response: { success, platform: "tiktok", originalAdGroupId, newAdGroupId, campaignId } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/tiktok/duplicate-adgroup" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"advertiserId":"6920267098044235778","adGroupId":"1800000000000002","targetCampaignId":"1800000000000003","newName":"Creative 07","dailyBudget":25,"startDate":"2026-09-28T17:00","endDate":"2026-10-02T17:00","timezone":"Europe/Paris"}' ``` These two TikTok duplicate endpoints return IDs synchronously, so they have no `operationKey`. For a different write that returns `{ accepted: true, isAsync: true, operationKey }`, poll `GET /v1/mutation-receipts/{operationKey}` with the same API key. `GET /v1/manage/mutation-status/{operationKey}` is not a REST route. - POST /v1/manage/axon/duplicate-campaign Duplicate an Axon/AppLovin campaign through Axon's public manage API. Body: { businessId, sourceCampaignId, newCampaignName, status ("LIVE"|"PAUSED")?, startDate? ("YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS"), workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/axon/duplicate-campaign" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"businessId":"1159321785","sourceCampaignId":"1786048","newCampaignName":"Campaign copy via API","status":"PAUSED","startDate":"2026-04-08T19:39:00","workspaceId":"workspace_abc"}' ``` ```json { "success": true, "campaignId": "1919062", "campaign": { "id": "1919062", "name": "Campaign copy via API", "status": "PAUSED", "type": "APP" }, "warnings": [ { "code": "AXON_APP_MIN_BUDGET_APPLIED", "message": "Axon APP campaigns require a minimum create budget of 500. Increased the create budget during duplication." } ] } ``` Notes: - This uses Axon's public `campaign/create` API and then applies a follow-up `campaign/update` when you request `PAUSED`. - APP campaigns preserve source tracking fields such as `tracking`, `platform`, `package_name`, and composite banner settings. - If Axon rejects the source APP budget during create, the API raises it to Axon's minimum create budget and returns a warning. - POST /v1/manage/duplicate-ad Duplicate a Facebook ad with optional creative modifications (primary text, headlines, URL, URL tags). Recreates creatives when necessary to remove deprecated 191x100 crop metadata or convert a standard image/video creative for an empty Dynamic Creative ad set. Body: { adId, accountId, targetAdSetId, copyCount (1-10), initialStatus ("ACTIVE"|"PAUSED"), useExistingPost? (boolean, default false), copyValues: { primaryText1-5?, headline1-5?, url?, urlTags?, adName? }, workspaceId? } Post ID / social proof (IMPORTANT): - By default each duplicate gets a brand-new Facebook post. Reactions, comments, shares, and video view counts from the source ad are NOT carried over. - Pass useExistingPost:true to reuse the source ad's Post ID (object_story_id) and keep that social proof. This mirrors "Use existing post" in Meta Ads Manager. - useExistingPost is ignored when any creative modification is supplied (primaryText*, headline*, url, urlTags), because copy/URL changes require a fresh post. adName alone is fine. - useExistingPost also cannot preserve the post when the target ad set is Dynamic Creative, or when the source creative has no effective_object_story_id. - Do not pass launch-style fields (postId / effectiveStoryId / object_story_id) on this endpoint — they are ignored. For launching with a known Post ID, use POST /v1/launch instead. Example — reuse the same Post ID (keeps social proof): ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-ad" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adId":"120012345678901234","accountId":"act_123","targetAdSetId":"120248289622780456","copyCount":1,"initialStatus":"PAUSED","useExistingPost":true,"copyValues":{"adName":"My Ad Copy"}}' ``` Example — change copy (forces a new post; omit useExistingPost or set false): ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/duplicate-ad" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adId":"120012345678901234","accountId":"act_123","targetAdSetId":"120248289622780456","copyCount":1,"initialStatus":"PAUSED","copyValues":{"primaryText1":"New headline","adName":"My Ad Copy"}}' ``` ```json { "success": true, "originalAdId": "120012345678901234", "results": [ { "copyNumber": 1, "success": true, "newAdId": "120012345678901235", "method": "copies" } ], "successCount": 1, "failCount": 0 } ``` Notes: - useExistingPost (default false): set true to reuse the source Post ID / object_story_id. - copyCount 1-10: Number of duplicates to create in one call. - deepCopy (default true): When true, copies all child objects (ads in ad sets, ad sets + ads in campaigns). Set to false to copy only the container. ## Manage (Delete + Edit + Status) ### POST /v1/manage/delete Delete Facebook or Pinterest campaigns, ad sets, or ads (up to 100 at once). Facebook: soft-delete (status DELETED). Pinterest: archived. Body: { entityIds (string[]), entityType ("campaigns"|"adsets"|"ads"), businessId, platform? ("facebook"|"pinterest"), workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/delete" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"entityIds":["120249137908810789","120249137908810790"],"entityType":"ads","businessId":"act_384730851257635"}' ``` ```json { "success": true, "results": [ { "id": "120249137908810789", "success": true }, { "id": "120249137908810790", "success": true } ], "successCount": 2, "failCount": 0 } ``` ### POST /v1/manage/update-status — Pause, Resume, or End ads / ad sets / campaigns One endpoint for three things: • PAUSE (stop immediately) — newStatus: "PAUSED" (Meta) or "DISABLE" (TikTok), no endTime. • RESUME (re-activate) — newStatus: "ACTIVE" (Meta) or "ENABLE" (TikTok), no endTime. • END on a schedule (Meta) — newStatus: "ACTIVE" + endTime (ISO 8601). Delivery keeps running until endTime, then stops. • EXTEND / CHANGE end date — call again with a new endTime; it overwrites the previous one. Works on campaigns, ad sets, and ads. Platform 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 API. Body: { entityId, entityType ("campaigns"|"adsets"|"ads"), newStatus ("ACTIVE"|"PAUSED" for Meta, "ENABLE"|"DISABLE" for TikTok), businessId, endTime? (ISO 8601, Meta only — schedule when delivery stops), workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-status" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"entityId":"120249137908810789","entityType":"adsets","newStatus":"ACTIVE","businessId":"act_384730851257635","endTime":"2026-04-22T23:59:59+0000"}' ``` ### POST /v1/manage/update-campaign-budget Set daily or lifetime budget for a Meta, TikTok or Snapchat campaign. Inputs are account-currency units (dollars); for Meta AdManage converts to cents internally and returns both amountDollars and amountCents. Body: { campaignId, businessId (act_* Meta ad account, TikTok advertiser id, or Snapchat ad account UUID), **either** dailyBudget **or** lifetimeBudget (number, ≥ 0), endTime? (ISO 8601, required when using lifetimeBudget on Meta), platform? ("meta"|"tiktok"|"snapchat", normally detected from businessId), workspaceId? } Note: Meta does not allow switching from daily to lifetime budget on an existing entity. Lifetime budget must be set at creation time. Snapchat: dailyBudget sets the campaign daily spend cap, lifetimeBudget the lifetime spend cap; setting one clears the other. Snapchat refuses a daily cap below a quarter of the ad squads' daily budgets (E2202, returned as the error message). Ad squads under a Smart Budget campaign take their budget from the campaign. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-campaign-budget" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"campaignId":"120247699100220456","businessId":"act_384730851257635","dailyBudget":150}' ``` Snapchat example (campaign lifetime spend cap): ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-campaign-budget" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"campaignId":"019ce657-2469-4b35-9674-fe16a5785071","businessId":"b975c7e6-7e3a-477f-b6c9-9e83b73e8109","lifetimeBudget":100}' ``` ### POST /v1/manage/update-adset-budget Set daily or lifetime budget for a Meta ad set, TikTok ad group or Snapchat ad squad. Inputs are account-currency units (dollars); for Meta AdManage converts to cents internally and returns both amountDollars and amountCents. Body: { adsetId (Snapchat: ad squad id), businessId (act_* Meta ad account, TikTok advertiser id, or Snapchat ad account UUID), **either** dailyBudget **or** lifetimeBudget (number, ≥ 0), endTime? (ISO 8601, required when using lifetimeBudget on Meta), platform? ("meta"|"tiktok"|"snapchat", normally detected from businessId), workspaceId? } Note: Meta does not allow switching from daily to lifetime budget on an existing ad set. Lifetime budget must be set at creation time. Snapchat: an ad has no budget of its own — find the ad's adSquadId with GET /v1/manage/snapchat/list-ads and set the budget there (it applies to every ad in the ad squad). Setting daily clears lifetime and vice versa. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-adset-budget" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"120249483901820456","businessId":"act_384730851257635","dailyBudget":25}' ``` Snapchat example (ad squad daily budget): ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-adset-budget" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"60d09510-9468-4c98-845f-639d85f34305","businessId":"b975c7e6-7e3a-477f-b6c9-9e83b73e8109","dailyBudget":50}' ``` ### POST /v1/manage/update-campaign-bidding Update Meta bidding for a campaign. This only applies to AUCTION campaigns using campaign budget optimization (CBO). Body: { campaignId, businessId (act_* ad account), bidStrategy? ("LOWEST_COST_WITHOUT_CAP"|"LOWEST_COST_WITH_BID_CAP"|"COST_CAP"|"TARGET_COST"), bidAmount? (number, ≥ 0, in dollars), workspaceId? } Important Meta behavior: - Campaign bid_strategy applies at the CBO campaign level. - For capped campaign strategies, Meta stores the cap amount on each child ad set as `bid_amount`. - When switching a CBO campaign from autobid to a capped campaign strategy, Meta requires an `adset_bid_amounts` map of every non-deleted child ad set ID to its bid amount. - AdManage now sends that `adset_bid_amounts` map in the campaign update request instead of patching child ad sets directly. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-campaign-bidding" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"campaignId":"120247699100220456","businessId":"act_384730851257635","bidStrategy":"LOWEST_COST_WITH_BID_CAP","bidAmount":35}' ``` ### POST /v1/manage/update-adset-bidding Update bidding for a Meta ad set or a Snapchat ad squad. Body: { adsetId (Snapchat: ad squad id), businessId (act_* Meta ad account or Snapchat ad account UUID), bidStrategy? (Meta: "LOWEST_COST_WITHOUT_CAP"|"LOWEST_COST_WITH_BID_CAP"|"COST_CAP"|"TARGET_COST"; Snapchat: "AUTO_BID"|"LOWEST_COST_WITH_MAX_BID"|"TARGET_COST", Meta names are mapped), bidAmount? (number, ≥ 0, in account currency), platform? ("meta"|"snapchat"), workspaceId? } Snapchat: bids live on ad squads only (update-campaign-bidding is Meta-only). bidAmount is required for LOWEST_COST_WITH_MAX_BID and TARGET_COST; bidAmount alone keeps the squad's current strategy. Ad squads under a Smart Budget campaign keep the campaign's strategy — only the amount can change. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-adset-bidding" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"120249483901820456","businessId":"act_384730851257635","bidStrategy":"COST_CAP","bidAmount":12.5}' ``` Snapchat example (max bid 3.00 on an ad squad): ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-adset-bidding" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"60d09510-9468-4c98-845f-639d85f34305","businessId":"b975c7e6-7e3a-477f-b6c9-9e83b73e8109","bidStrategy":"LOWEST_COST_WITH_MAX_BID","bidAmount":3}' ``` ### POST /v1/manage/update-name Rename a Meta campaign, ad set, or ad. Body: { entityId, entityType ("campaigns"|"adsets"|"ads"), businessId (act_* ad account), name, workspaceId? } Aliases: campaignId, adsetId/adSetId, and adId may be used instead of entityId. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-name" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"entityType":"adsets","adsetId":"120249483901820456","businessId":"act_384730851257635","name":"Prospecting - US - Broad"}' ``` ### POST /v1/manage/disable-app-events Disable Meta App events tracking on an existing ad. This removes `application` tracking specs from the ad while preserving website pixel and offline dataset tracking specs. Body: { adId, businessId (act_* ad account), workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/disable-app-events" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adId":"120249137908810789","businessId":"act_384730851257635"}' ``` ### POST /v1/manage/update-adset-spending-limits Set or clear CBO ad set spending limits (daily minimum spend target and daily maximum spend cap) for an ad set inside a campaign budget optimization (CBO) campaign. Inputs are dollars; AdManage converts to Meta cents internally and sends `daily_min_spend_target` / `daily_spend_cap`. The response echoes both dollars and cents for each limit. Body: { adsetId, businessId (act_* ad account), dailyMinSpend? (number, ≥ 0, in dollars), dailySpendCap? (number, ≥ 0, in dollars), clearDailyMin? (boolean), clearDailyMax? (boolean), workspaceId? } Rules: - Provide at least one of dailyMinSpend, dailySpendCap, clearDailyMin, or clearDailyMax. - Do not send a value and its clear flag for the same field (e.g. dailyMinSpend + clearDailyMin). - When both are set, dailyMinSpend cannot exceed dailySpendCap. - clearDailyMin / clearDailyMax send 0 to Meta to remove the limit. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/update-adset-spending-limits" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adsetId":"120249483901820456","businessId":"act_384730851257635","dailyMinSpend":100,"dailySpendCap":500}' ``` ### POST /v1/manage/edit-ads Batch edit existing Facebook ads — change name, primary text, headlines, descriptions, URL, CTA, UTM tags, creative enhancements. Body: { accountId, ads: [{ adId, copyValues: { adName?, primaryText1?, headline1?, description1?, url?, urlTags?, cta?, creativeEnhancements? ("on"|"off") } }] } ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/edit-ads" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"accountId":"act_123","ads":[{"adId":"120249137908810789","copyValues":{"primaryText1":"Updated text","headline1":"New headline"}}]}' ``` ### GET /v1/manage/lead-forms List active lead forms for a Facebook Page. Required when launching into lead gen ad sets. The API resolves the Page access token from the stored Facebook user token before reading `/{pageId}/leadgen_forms`. Query: pageId (required), workspaceId? ```bash curl -sS "https://api.admanage.ai/v1/manage/lead-forms?pageId=470703006115773" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": "456789123", "name": "Contact Us Form", "status": "ACTIVE", "created_time": "2026-02-18T08:25:12+0000" } ] } ``` ### POST /v1/manage/refresh-adsets Fetch/refresh ad sets from the Facebook Graph API. Supports caching and cooldown. Body: { businessId (required, act_*), type? ("all"|"active"|"paused"), hardRefresh?, forceRefresh?, workspaceId? } ### POST /v1/manage/duplicate-adset-advanced Duplicate an ad set with optional targeting updates (locations, custom audiences) and ad duplication. Body: { adsetId, accountId, newAdSetName?, duplicateAds? (boolean), duplicateAdsStatus?, singleAdId?, locationTargeting?, customAudiencesInclude?, customAudiencesExclude?, workspaceId? } ## Manage (Library) ### POST /v1/library/assets/{id}/update Update a media asset's metadata. Body: { name?, uploaderStatus? ("raw"|"in_progress"|"approved"|"archived"), rating? (1-5), smartTags? (string[]) } ```bash curl -sS -X POST "https://api.admanage.ai/v1/library/assets/12345/update" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"uploaderStatus":"approved","rating":5,"smartTags":["hero","q1"]}' ``` ### DELETE /v1/library/assets/{id} Permanently delete a media asset (same as deleting it in the web app). {id} is the asset "id" from GET /v1/library/assets (not adid). Returns 404 if the asset is not in your company. ```bash curl -sS -X DELETE "https://api.admanage.ai/v1/library/assets/12345" \ -H "Authorization: Bearer " ``` ### POST /v1/library/boards Create a new board (folder) in the creative library. Body: { name (required), description?, parentId? (number, for nesting), visibility? ("team"|"private") } ### POST /v1/library/boards/{id}/assets Add an asset to a board. Body: { adId (number, asset ID) } ### DELETE /v1/library/boards/{id}/assets Remove an asset from a board (unlinks only, doesn't delete the asset). Query: adId (required) ## Comments (Reply + Hide) Respond to or moderate Facebook ad comments. Both endpoints call the Facebook Graph API on your behalf using your connected token. ### POST /v1/comments/reply Reply to a Facebook ad comment. The reply is posted as the page that owns the ad. Body: | Field | Required | Description | |-------|----------|-------------| | commentId | yes | Facebook comment ID (e.g. "1542661021111818_1245574530890886") | | message | yes | Reply text | | workspaceId | no | Workspace ID to resolve the correct Facebook token | ```bash curl -sS -X POST "https://api.admanage.ai/v1/comments/reply" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"commentId":"1542661021111818_1245574530890886","message":"Thanks for your feedback!"}' ``` ```json { "success": true, "data": { "replyId": "1542661021111818_9988776655", "commentId": "1542661021111818_1245574530890886" } } ``` ### POST /v1/comments/hide Hide or unhide a Facebook ad comment from public view. Body: | Field | Required | Description | |-------|----------|-------------| | commentId | yes | Facebook comment ID | | hide | yes | true to hide, false to unhide | | workspaceId | no | Workspace ID to resolve the correct Facebook token | ```bash curl -sS -X POST "https://api.admanage.ai/v1/comments/hide" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"commentId":"1542661021111818_1245574530890886","hide":true}' ``` ```json { "success": true, "data": { "commentId": "1542661021111818_1245574530890886", "hidden": true } } ``` ## Media (Upload Flow) ### POST /v1/media/get-upload-url Get a presigned URL for direct file upload (expires in 1 hour). Body: { fileName (required) } ```bash curl -sS -X POST "https://api.admanage.ai/v1/media/get-upload-url" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"fileName":"creative.mp4"}' ``` Upload flow: get-upload-url → upload file to returned URL → confirm-upload → (optional) generate-thumbnail ### POST /v1/media/confirm-upload Register an uploaded file in the media library after uploading via presigned URL. Body: { url (required, the publicUrl from get-upload-url, never the presigned url), fileName? } ### POST /v1/media/generate-thumbnail Generate a thumbnail for a video file (non-blocking). Body: { url (required, media.admanage.ai video URL) } ### POST /v1/media/subtitles Start a subtitle render job that burns styled subtitles into a video using the Create/Subtitle Maker renderer. Body: { videoUrl (required), segments?, srtText?, srtUrl?, operation?, stylePreset?, positionPreset?, fontFamily?, fontSize?, color?, outlineColor?, wordsPerCaption?, maxCaptionDuration?, params? } Backpressure: each company can have up to 3 active subtitle jobs by default, tracked through the existing Redis limiter with in-memory fallback. Extra submissions return 429 until existing jobs finish or expire from tracking. After a jobId exists, do not resubmit the same render. Poll GET /v1/media/subtitles/{jobId} or use the MCP wait_for_subtitled_video helper. ```bash curl -sS -X POST "https://api.admanage.ai/v1/media/subtitles" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"videoUrl":"https://media.admanage.ai/acme/source.mp4","segments":[{"start":0,"end":1.2,"text":"Launch faster"}],"stylePreset":"bold","positionPreset":"bottom-third"}' ``` Poll GET /v1/media/subtitles/{jobId}; when status is succeeded, call POST /v1/media/subtitles/{jobId}/publish. ### GET /v1/media/subtitles/{jobId} Poll subtitle render status. Status values: queued, running, succeeded, failed. ### POST /v1/media/subtitles/{jobId}/publish Upload a completed subtitle render result to media.admanage.ai and return a durable URL. Body: { fileName?, registerInLibrary? } ## Batch (Ad Delivery Status) ### GET /v1/adbatches/{id}/ad-delivery-statuses Get ad delivery status for all ads in a batch (Meta only). Cached for 15 minutes. Query: refresh? (true to force refresh) Every response includes launch-stage error context (`batchStatus`, `summaryStatus`, `launchError`, `launchFailedDetails`, `launchErrorMessage`, `finalMessage`) so callers can tell when a batch failed before ads were created and see the actual error message. ```bash curl -sS "https://api.admanage.ai/v1/adbatches/9911/ad-delivery-statuses" \ -H "Authorization: Bearer " ``` ```json { "success": true, "batchId": 9911, "adDeliveryStatuses": { "120249137908810789": { "effectiveStatus": "ACTIVE", "checkedAt": "2026-03-30T10:15:00.000Z" }, "120249137908810790": { "effectiveStatus": "PENDING_REVIEW", "checkedAt": "2026-03-30T10:15:00.000Z" } }, "fromCache": true, "batchStatus": "success", "summaryStatus": "success", "launchError": null, "launchFailedDetails": null, "launchErrorMessage": null, "finalMessage": "2 ads launched" } ``` ## Apple Ads Connect Apple Ads in AdManage Connect first, then use the connected businessId (apple_ followed by the numeric Apple advertiser ID) and workspaceId from GET /v1/adaccounts. Use an AdManage customer API key, never an Apple token. The API and MCP use the same paused-launch and reviewed-bulk engine as /launch, including actual workspace membership, user role, billing and live Apple access checks. Read-only API/OAuth scopes cannot submit or resume writes. | Endpoint | MCP equivalent | | --- | --- | | GET /v1/apple-ads/apps?workspaceId&businessId&query | list_apple_ads_apps | | GET /v1/apple-ads/campaigns?workspaceId&businessId | list_apple_ads_campaigns | | GET /v1/apple-ads/entities?workspaceId&businessId&level&startDate&endDate&campaignIds | list_apple_ads_entities | | POST /v1/apple-ads/launch | launch_apple_ads | | POST /v1/apple-ads/bulk (action: preview) | preview_apple_ads_bulk_edit | | POST /v1/apple-ads/bulk (action: apply) | apply_apple_ads_bulk_edit | | GET /v1/apple-ads/jobs?workspaceId&businessId&id | get_apple_ads_job | | GET /v1/apple-ads/jobs?workspaceId&businessId | list_apple_ads_jobs | | POST /v1/apple-ads/jobs | retry_apple_ads_launch | | POST /v1/apple-ads/keywords | add_apple_ads_keywords | | POST /v1/apple-ads/update | update_apple_ads_entity | | GET /v1/apple-ads/history?workspaceId&businessId&level&id&days | get_apple_ads_history | | GET /v1/apple-ads/keyword-suggestions?workspaceId&businessId&adGroupId&terms | suggest_apple_ads_keywords | | GET /v1/apple-ads/findings?workspaceId&businessId&startDate&endDate | get_apple_ads_findings | | GET /v1/apple-ads/product-pages?workspaceId&businessId&adamId | list_apple_ads_product_pages | | POST /v1/apple-ads/product-pages | create_apple_ads_product_page_ad | | GET/POST /v1/apple-ads/drafts | (Launch Drafts) | Launch options: existingCampaignId adds ad groups to that campaign (no countries/budget needed; nothing on the campaign changes); bidStrategy MANUAL_CPT (default) or MAX_CONVERSIONS (needs targetCpa and one Search Match ad group); adGroups[].targeting {minAge,maxAge,gender:"M"|"F",devices:["IPHONE"|"IPAD"]}; startAt/endAt run window in the account timezone (YYYY-MM-DDTHH:mm). One campaign per country = one launch per country, each with its own requestId. Keywords body: {workspaceId,businessId,requestId,additions:[{kind:"keyword",adGroupId,text,matchType,bid?,replaces?},{kind:"negative",scope:"campaign"|"ad_group",targetId,text,matchType}]}. Existing keywords are skipped. replaces= pauses the old keyword after the new one exists (Apple can't edit text or match type); the old keyword must be live in the same ad group, and a replacement that matches it (text compared ignoring case) keeps it running. Runs as a job: poll get_apple_ads_job. Update body: {workspaceId,businessId,expected?,update:{level,id,...}}. Levels: campaign (status, dailyBudget, name, countries, endAt|null), ad_group (status, bid, name, searchMatch, targeting), keyword (status, bid), ad (status), negative_keyword (status, remove). expected is the bid/budget the user saw; a different current Apple value returns 409 changed_in_apple. Launch body: {workspaceId,businessId,requestId,spec:{appId,campaignName,countries:["GB"],dailyBudget:"5.00",negatives:[{text,matchType}],adGroups:[{name,bid:"0.50",searchMatch:false,keywords:[{text,matchType:"EXACT",bid:"0.40"}]}]}}. Amounts are decimal strings in account currency. EXACT/BROAD only. Up to 20 groups, 1000 keywords/group and 1000 campaign negatives. Creates PAUSED campaign and ad groups; default App Store product page only. Each group needs keywords or Search Match. Apple may automatically supply a default search ad without a separate ad ID; results label that automatic. Bulk preview body: {workspaceId,businessId,action:"preview",level:"keyword",ids:["123"],change:{kind:"increase",value:10,cap:"0.55"}}. Levels: campaign, ad_group, keyword, ad, negative_keyword. Changes: status (PAUSED/ENABLED), set (decimal string), increase (percent plus cap), decrease (percent below 100). Ads/negatives support status only. Campaign amounts mean daily budgets; group/keyword amounts mean manual bids. Preview makes no Apple writes but requires write access. Show the exact before/after values to the user, then apply {workspaceId,businessId,action:"apply",previewId,requestId}. Preview expires in 10 minutes; only its stored values are applied, with conflict checks and readback. Enabling may start paid delivery; obtain explicit user authorization for that change. Retain requestId (a UUID) and immutable payload for retrying the same launch/apply after a lost response. Changed content with that UUID is rejected. Acceptance returns a saved job, not completed ads: poll get_apple_ads_job every five seconds until job.job.finished. Outcomes include success, automatic, partial, failed, conflict and unknown. Working writes interrupted after a possible side effect become unknown and are never replayed. Retry body {workspaceId,businessId,id} retries known failed launch steps only, preserving successful IDs; bulk failures need a fresh preview. Only the creator may continue or retry. Continue polling to resume bounded execution segments; reopening /launch also resumes them. This is not a standalone durable worker queue. Entity reads use campaigns/adgroups/adrows (ads with their product page)/keywords/negativekeywords (campaign and ad-group negatives)/searchterms (legacy ads/negatives still work), YYYY-MM-DD dates and comma-separated campaignIds for child levels (MCP accepts arrays). Maximum 60 campaigns, 5000 entities/campaign, 100 IDs per bulk review. Apps return up to 100 matching owned apps. Missing metrics remain null. ## YouTube ### POST /v1/google-ads/upload-youtube-video Upload a video URL to Google's managed YouTube ad-storage channel (no personal YouTube channel required). Uses Google Ads OAuth for accountId. Privacy is always UNLISTED. Body: { accountId (required), videoUrl (required), title (required), description?, workspaceId? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/google-ads/upload-youtube-video" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"accountId":"1234567890","videoUrl":"https://media.admanage.ai/acme/creative.mp4","title":"Product Demo"}' ``` ```json { "success": true, "youtubeVideoId": "dQw4w9WgXcQ", "resourceName": "customers/1234567890/youTubeVideoUploads/42", "state": "PROCESSED" } ``` MCP equivalent: `upload_google_ads_youtube_video`. Pass the returned `youtubeVideoId` to `launch_google_ads` as `videos[].youtubeVideoId`. ### POST /v1/youtube/upload-from-url Upload a video to YouTube from a URL. Useful for API and MCP tracker workflows that need YouTube video IDs for Google Ads. Body: { videoUrl (required), title?, description?, privacy? ("public"|"unlisted"|"private"), channelId?, playlistId?, youtubeTokenId?, workspaceId?, adId?, selfDeclaredMadeForKids? } ```bash curl -sS -X POST "https://api.admanage.ai/v1/youtube/upload-from-url" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"videoUrl":"https://media.admanage.ai/acme/creative.mp4","title":"Product Demo","description":"Tracker-provided description","privacy":"unlisted"}' ``` ```json { "success": true, "videoId": "dQw4w9WgXcQ", "youtubeUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ" } ``` MCP equivalent: `upload_youtube_video_from_url`. Pass the returned `videoId` to `launch_google_ads` as `videos[].youtubeVideoId`. ### GET /v1/youtube/video-status Check YouTube processing status, title, and duration for up to 50 uploaded video IDs. Query: videoIds (comma-separated, required), workspaceId? ```bash curl -sS "https://api.admanage.ai/v1/youtube/video-status?videoIds=dQw4w9WgXcQ&workspaceId=workspace_abc123" \ -H "Authorization: Bearer " ``` ```json { "videos": { "dQw4w9WgXcQ": { "processing": false, "uploadStatus": "processed", "title": "Product Demo", "durationSeconds": 31, "durationFormatted": "0:31" } } } ``` MCP equivalent: `get_youtube_video_status`. ### POST /v1/youtube/wait-for-processing Poll YouTube until uploaded videos finish processing or the wait limit is reached. Use before launching Google Ads with newly uploaded videos. Body: { videoIds (required array), workspaceId?, maxWaitMs? } — maxWaitMs is capped at 600000. ```bash curl -sS -X POST "https://api.admanage.ai/v1/youtube/wait-for-processing" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"videoIds":["dQw4w9WgXcQ"],"maxWaitMs":300000}' ``` ```json { "allReady": true, "timedOut": false, "videos": { "dQw4w9WgXcQ": { "ready": true, "uploadStatus": "processed" } } } ``` MCP equivalent: `wait_for_youtube_processing`. ## Google Ads Manage Google Ads campaigns (Performance Max, Demand Gen). All endpoints require accountId (Google Ads customer ID). ### GET /v1/google-ads/campaigns List cached campaigns and ad groups. Query: accountId (required) MCP equivalent: `list_google_ads_campaigns`. ```bash curl -sS "https://api.admanage.ai/v1/google-ads/campaigns?accountId=7037703309" \ -H "Authorization: Bearer " ``` ### GET /v1/google-ads/campaigns/bidding Read each campaign's bidding strategy live from Google Ads: biddingStrategyType and biddingStrategyLabel (the Google Ads UI name), scope (standard, or portfolio with id, name and owning account), and settings: targetCpa and min/maxCpcBidLimit (account currency units, see currencyCode), targetRoas (multiplier, 4.5 = 450%), targetImpressionShare, enhancedCpc. Query: accountId (required), campaignIds (optional, comma-separated, up to 500; omitted reads every non-removed campaign), workspaceId? MCP equivalent: `get_google_ads_campaign_bidding`. ```bash curl -sS "https://api.admanage.ai/v1/google-ads/campaigns/bidding?accountId=7037703309&campaignIds=21234567890" \ -H "Authorization: Bearer " ``` ### POST /v1/google-ads/campaigns/toggle-status Toggle campaign ENABLED/PAUSED. Body: { accountId, campaignId, status ("ENABLED"|"PAUSED") } ### POST /v1/google-ads/campaigns/rename Rename a campaign. Body: { accountId, campaignId, newName } ### POST /v1/google-ads/campaigns/update-budget Update a campaign's average daily budget in account currency units. Body: { accountId, campaignId, dailyBudget, workspaceId? } MCP equivalent: `update_google_ads_campaign_budget`. ### POST /v1/google-ads/campaigns/update-bidding Update exactly one tCPA or tROAS target on the campaign's active standard or portfolio bidding strategy. Body: { accountId, campaignId, targetCpa?, targetRoas?, workspaceId? } targetCpa is in account currency units. targetRoas is a multiplier (3.5 = 350%). Updating a shared portfolio strategy affects every campaign attached to that strategy. MCP equivalent: `update_google_ads_campaign_bidding`. ### POST /v1/google-ads/duplicate-campaign Duplicate a campaign with all ad groups, ads, and keywords. Body: { campaignId, accountId, newName, status? } MCP equivalent: `duplicate_google_ads_campaign`. ### POST /v1/google-ads/duplicate-ad-group Duplicate an ad group with ads and keywords. Body: { campaignId, adGroupId, accountId, newName, status? } MCP equivalent: `duplicate_google_ads_ad_group`. ### POST /v1/google-ads/duplicate-ad Duplicate a single ad (RSA, RDA, generic). Body: { adGroupId, adId, accountId, status? } ### POST /v1/google-ads/ad-details Get Demand Gen ad creative data (read-only despite POST). Body: { accountId, adGroupId, adId } ### POST /v1/google-ads/add-text-assets Add headlines, long headlines, descriptions to PMax asset groups. Body: { accountId, assetGroupIds (string[]), headlines?, longHeadlines?, descriptions? } ### POST /v1/google-ads/add-assets Add video/image assets to PMax asset groups or Demand Gen ads. Rate limited: 5 req/min. Body: { accountId, assetGroupIds, videos? [{ youtubeVideoId }], images? [{ base64, fieldType, aspectRatio }] } ### POST /v1/google-ads/upload-image-assets Upload images to a Google Ads account's Asset library without attaching them to any ad, ad group or campaign. Images only. Max 50 per request. Rate limited: 10 req/min. Body: { accountId (required), images (required) [{ libraryAssetId? | sourceUrl? | base64?, name? }], workspaceId? } - libraryAssetId: an AdManage media library asset (fetched server-side). sourceUrl: any public direct image link. base64: raw bytes. - Asset name = name, else the library asset name, with the file extension dropped. - Duplicate check: an image asset already in the account with the same name and byte size is returned with alreadyExisted: true instead of being uploaded again. ```bash curl -sS -X POST "https://api.admanage.ai/v1/google-ads/upload-image-assets" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"accountId":"1234567890","images":[{"libraryAssetId":123456},{"sourceUrl":"https://media.admanage.ai/acme/hero.png","name":"DG_01_hero_1x1"}]}' ``` ```json { "success": true, "message": "Uploaded 1 image(s) to the Google Ads Asset library, 1 already there", "results": [ { "libraryAssetId": 123456, "name": "DG_01_CW16AD12IMG1_1x1", "success": true, "alreadyExisted": false, "assetId": "419321299161", "resourceName": "customers/1234567890/assets/419321299161" }, { "name": "DG_01_hero_1x1", "success": true, "alreadyExisted": true, "assetId": "419321299162", "resourceName": "customers/1234567890/assets/419321299162" } ] } ``` MCP equivalent: `upload_google_ads_image_assets`. Use the returned assetId in `launch_google_ads` as an existing asset (`{ "asset": "" }`). ### POST /v1/google-ads/remove-assets Remove an asset from a PMax asset group. Body: { accountId, assetId, assetGroupId } ### POST /v1/google-ads/update-assets Update text assets (immutable: removes old + creates new). Body: { accountId, editedAssets [{ assetId, text, originalText, type, assetGroupId }] } ### POST /v1/google-ads/launch Orchestrated launch — creates batch, runs all operations, updates batch. Returns 202. Rate limited: 3 req/min. Body: { accountId, accountName, assetGroupIds, assetGroupNames, headlines?, descriptions?, videos?, images?, deletions?, editedAssets?, draftAds? } New ads go in draftAds [{ draftId, name, type, adGroupId, status, sourceCreative { headlines, longHeadlines, descriptions, finalUrls, businessName { text } }, assignedVideos?, assignedImages?, assignedLogos? }]. Drafts are checked like the web builder before a batch is created, and refused with 400 listing every issue: each ad type's copy, image, logo, business name and final URL minimums (Demand Gen needs a business name and a square logo, assignedLogos [{ sourceUrl or base64, aspectRatio: "1:1" }]), Search/App headline and description lengths, Search path length, duplicate text, mixed Demand Gen media, image/logo pixel size and ratio, and a destination (adGroupId; campaignId for Performance Max). Adding images, logos or videos to Performance Max asset groups is refused past 20 / 5 / 15 per group. Send "validationOverrideRowCount": 1 to launch past minimums anyway; maximums and malformed input are never skippable. Non-blocking notes (an image the server could not fetch, App images that will be left out) come back in "warnings". ```json { "success": true, "batchId": 12345, "slug": "unique-slug", "isAsync": true, "warnings": ["..."] } ``` To save this body for review instead of launching it, POST it to /v1/drafts with `"platform": "google_ads"` (see Launch Drafts). ## Conversions (Meta CAPI) ### GET /v1/conversions/pixels List Meta pixels for an ad account. Query: businessId (required), workspaceId? ```bash curl -sS "https://api.admanage.ai/v1/conversions/pixels?businessId=act_123" \ -H "Authorization: Bearer " ``` ### POST /v1/conversions/events Send custom events to Meta Conversions API (CAPI). PII is automatically SHA-256 hashed. Body: { businessId, events [{ event_name, event_time, user_data: { em?, ph?, external_id? }, custom_data?: { value?, currency? } }], test_event_code?, workspaceId? } Rate limit: 50 req/min (up to 1000 events each = 50,000 events/min). ## Facebook Ad Rules (Native) Create, manage, and monitor native Facebook Ad Rules that run on Meta's servers. ### GET /v1/manage/rules List all rules for an account. Query: accountId (required), workspaceId? ### GET /v1/manage/rules/:id Get a specific rule. Query: workspaceId? ### POST /v1/manage/rules Create a new rule. Body: { accountId, name, actionType ("TURN_OFF"|"TURN_ON"|"NOTIFICATION"|"INCREASE_DAILY_BUDGET"|"DECREASE_DAILY_BUDGET"|"INCREASE_LIFETIME_BUDGET"|"DECREASE_LIFETIME_BUDGET"), entityType? ("AD"|"ADSET"|"CAMPAIGN"), conditions [{ field, operator, value }], scheduleType? ("DAILY"|"CONTINUOUS"), timeRange?, budgetValue?, budgetValueType? ("PERCENT"|"ABSOLUTE"), maxDailyCap?, workspaceId? } ### PATCH /v1/manage/rules/:id Update a rule. Same body fields as create (all optional). ### DELETE /v1/manage/rules/:id Delete a rule. ### GET /v1/manage/rules-history Get rule execution history. Query: accountId (required), hideNoChanges? ("true"|"false"), workspaceId? ## Automations ### List Rules - GET /v1/automations Query: page, limit, status, workspaceId, search ```bash curl -sS "https://api.admanage.ai/v1/automations?page=1&limit=25&status=active" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 1, "name": "Pause low ROAS ads", "status": "active", "actionType": "pause_ad", "accountId": "act_123456789", "frequency": "daily", "scheduledDate": "2026-02-27", "scheduledTime": "09:00", "workspaceId": "workspace_abc", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-25T14:30:00.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 } } ``` ### Get Rule - GET /v1/automations/:id Returns the rule with its 10 most recent executions. ```bash curl -sS "https://api.admanage.ai/v1/automations/1" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "id": 1, "name": "Pause low ROAS ads", "status": "active", "flow": { "nodes": [ { "id": "node-trigger-1", "type": "trigger", "service": "meta-ads", "event": "Performance Threshold", "config": { "accountId": "act_123456789" }, "position": 1 }, { "id": "node-action-2", "type": "action", "service": "meta-ads", "event": "Pause Ad", "config": { "accountId": "act_123456789", "targetIds": "{{node-trigger-1.qualifyingAdIds}}" }, "position": 2 } ] }, "actionType": "pause_ad", "accountId": "act_123456789", "targetId": null, "newName": null, "frequency": "daily", "scheduledDate": "2026-02-27", "scheduledTime": "09:00", "dayOfWeek": null, "dayOfMonth": null, "startDate": null, "endDate": null, "userId": "usr_01HXYZ", "userEmail": "user@acme.com", "company": "acme", "workspaceId": "workspace_abc", "createdAt": "2026-02-20T10:00:00.000Z", "updatedAt": "2026-02-25T14:30:00.000Z", "executions": [ { "id": 101, "status": "completed", "executedAt": "2026-02-26T09:00:05.000Z", "completedAt": "2026-02-26T09:00:12.000Z", "duration": 7000, "errorMessage": null } ] } } ``` ### Create Rule - POST /v1/automations Body: name (required), flow (required, object with nodes array), actionType (required), accountId (required), targetId?, newName?, frequency? ("one-time"|"daily"|"weekly"|"monthly", default "one-time"), scheduledDate?, scheduledTime?, dayOfWeek?, dayOfMonth?, startDate?, endDate?, status? (default "active"), workspaceId? Flow node shape: { id, type ("trigger"|"action"|"filter"|"delay"|"approval"), service, event, config, position }. Notification action node: service "notification", event "Send Notification", config { notificationMethod: "email"|"slack"|"both", slackChannelOverride?: { id, name }, emailRecipients?: string[], customMessage?: string }. Webhook action node: service "webhook", event "Send Webhook", config { url, method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", headers?: [{ key, value }], body?: string }. Google Ads trigger node: service "google-ads", event "Performance Threshold", config { accountId, entityLevel: "campaign"|"ad_group"|"ad", criteria, campaignTypes?: ("SEARCH"|"PERFORMANCE_MAX"|"MULTI_CHANNEL"|"DEMAND_GEN"|"DISPLAY"|"VIDEO"|"SHOPPING")[] (MULTI_CHANNEL = App; empty = all), campaignNameFilterType?, campaignNameFilter?, adGroupNameFilterType?, adGroupNameFilter? }. Evaluates campaigns, ad groups or ads and supports only these criteria metrics: spend, impressions, clicks, ctr, cpc, cpm, conversions, conversionValue, cpa, roas, costPerResult, resultCount, adAge, adName. A rule using only volume metrics that match 0 (e.g. spend = 0) also checks enabled entities with no delivery. Condition metric adAge = days since the entity was created or its campaign started (Google change history; threshold at most 28). Outputs qualifyingCampaignIds, qualifyingAdGroupIds, qualifyingAdGroupAdIds (adGroupId~adId, ad level), qualifyingEntities, qualifyingCount, entityLevel. Performance Max campaigns have no ad groups or ads, so use entityLevel "campaign" for them. Google Ads action nodes: service "google-ads", event "Pause Campaign"|"Enable Campaign" (config { accountId?, targetIds: "{{node-trigger-1.qualifyingCampaignIds}}" }), "Pause Ad Group"|"Enable Ad Group" (targetIds "{{node-trigger-1.qualifyingAdGroupIds}}"), "Pause Ad"|"Enable Ad" (targetIds "{{node-trigger-1.qualifyingAdGroupAdIds}}"), "Change Budget" (config { budgetChangeType: "set"|"increase"|"decrease", budgetValueType: "amount"|"percentage", budgetValue, allowSharedBudget? }), or "Update Target CPA/ROAS" (config { biddingTarget: "target_cpa"|"target_roas", biddingValue }). Campaigns on a shared budget are skipped by Change Budget unless allowSharedBudget is true. Google Ads auto-applied keyword trigger node: service "google-ads", event "Auto-Applied Keyword Detected", config { accountId, blockedTerms: string[], campaignIds?, keywordSource?: "auto_applied"|"any" (default "auto_applied"), maxPerRun? (default 200), checkFrequency?, checkDays?, checkTime? }. Finds keywords Google's auto-apply recommendations added to Search campaigns and matches them against blockedTerms. blockedTerms is matched as whole words, case-insensitively ("free" matches "free trial" but not "freedom"); an empty blockedTerms list matches nothing, never everything. keywordSource "auto_applied" relies on Google's change history, which only retains 30 days. Outputs qualifyingKeywords, qualifyingCount, qualifyingCampaignIds, qualifyingAdGroupIds, accountId, keywordText, matchedTerm. Google Ads search term trigger node: service "google-ads", event "Search Term Matched", config { accountId, blockedTerms: string[], campaignType?: "all"|"shopping"|"search" (default "all"), campaignIds?, lookbackDays? (default 30), maxPerRun? (default 200), checkFrequency?, checkDays?, checkTime? }. Scans the search terms report of Search and/or Shopping campaigns (Shopping has no keywords; Performance Max is not covered), skips terms already excluded, and matches the rest against blockedTerms as whole words, case-insensitively; an empty blockedTerms list matches nothing. Outputs qualifyingKeywords, qualifyingCount, qualifyingCampaignIds, qualifyingAdGroupIds, accountId, searchTerm, matchedTerm. Pair it with "Add Negative Keywords"; originalKeywordHandling is ignored for search terms. Google Ads negative-keyword action node: service "google-ads", event "Add Negative Keywords", config { negativeLevel?: "ad_group"|"campaign" (default "ad_group"), negativeMatchType?: "EXACT"|"PHRASE"|"BROAD" (default "EXACT"), originalKeywordHandling?: "remove"|"pause"|"leave" (default "remove") }. Adds the matched keywords as negatives at the configured level and applies the configured handling to the original keyword; it consumes the preceding trigger's qualifyingKeywords automatically, so no targetIds field is needed. ```bash curl -sS -X POST "https://api.admanage.ai/v1/automations" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name":"Notify on high spend","flow":{"nodes":[{"id":"node-trigger-1","type":"trigger","service":"meta-ads","event":"Performance Threshold","config":{"accountId":"act_123456789","criteria":{"conditions":[{"metric":"spend","operator":">","value":1000}],"logic":"AND","lookbackDays":1}},"position":1},{"id":"node-action-2","type":"action","service":"notification","event":"Send Notification","config":{"notificationMethod":"email","emailRecipients":["ops@example.com"],"customMessage":"Spend threshold reached"},"position":2}],"edges":[{"source":"node-trigger-1","target":"node-action-2"}]},"actionType":"notify","accountId":"act_123456789","frequency":"daily","scheduledTime":"09:00","workspaceId":"workspace_abc"}' ``` ```json { "success": true, "data": { "id": 2, "name": "Notify on high spend", "status": "active", "flow": { "nodes": [ { "id": "node-trigger-1", "type": "trigger", "service": "meta-ads", "event": "Performance Threshold", "config": { "accountId": "act_123456789" }, "position": 1 }, { "id": "node-action-2", "type": "action", "service": "notification", "event": "Send Notification", "config": { "notificationMethod": "email", "emailRecipients": ["ops@example.com"] }, "position": 2 } ] }, "actionType": "notify", "accountId": "act_123456789", "frequency": "daily", "scheduledDate": "2026-02-27", "scheduledTime": "09:00", "workspaceId": "workspace_abc", "createdAt": "2026-02-27T15:00:00.000Z", "updatedAt": "2026-02-27T15:00:00.000Z" } } ``` ### Update Rule - PATCH /v1/automations/:id Body: any combination of name, flow, actionType, accountId, targetId, newName, status, frequency, scheduledDate, scheduledTime, dayOfWeek, dayOfMonth, startDate, endDate, workspaceId. At least one field required. ```bash curl -sS -X PATCH "https://api.admanage.ai/v1/automations/2" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"status":"paused"}' ``` ```json { "success": true, "data": { "id": 2, "name": "Pause low ROAS ads", "status": "paused", "frequency": "daily", "updatedAt": "2026-02-27T16:00:00.000Z" } } ``` ### Delete Rule - DELETE /v1/automations/:id ```bash curl -sS -X DELETE "https://api.admanage.ai/v1/automations/2" \ -H "Authorization: Bearer " ``` ```json { "success": true, "message": "Rule 2 deleted" } ``` ### Execute Rule by ID - POST /v1/automations/:id/execute Runs an existing saved rule. Returns 202 Accepted with an executionId to poll. ```bash curl -sS -X POST "https://api.admanage.ai/v1/automations/1/execute" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "executionId": 102, "status": "running", "message": "Poll GET /v1/automations/executions/102 for status." } } ``` ### Execute Inline (no saved rule) - POST /v1/automations/execute Body: flow (required, object with nodes array), actionType (required), accountId (required), name?, targetId?, newName?, dryRun? (boolean), workspaceId? Returns 202 Accepted with an executionId to poll. ```bash curl -sS -X POST "https://api.admanage.ai/v1/automations/execute" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"flow":{"nodes":[{"id":"node-action-1","type":"action","service":"webhook","event":"Send Webhook","config":{"url":"https://example.test/webhook","method":"POST","headers":[{"key":"Content-Type","value":"application/json"}],"body":"{\"text\":\"Automation fired\"}"},"position":1}]},"actionType":"webhook","accountId":"act_123456789","dryRun":true}' ``` ```json { "success": true, "data": { "executionId": 103, "status": "running", "message": "Poll GET /v1/automations/executions/103 for status." } } ``` ### List Executions - GET /v1/automations/executions Query: page, limit, status ("running"|"completed"|"failed"|"scheduled_delay"|"awaiting_approval"), automationRuleId, workspaceId ```bash curl -sS "https://api.admanage.ai/v1/automations/executions?page=1&limit=10&status=completed" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 101, "automationRuleId": 1, "name": "Pause low ROAS ads", "actionType": "pause_ad", "status": "completed", "executedAt": "2026-02-26T09:00:05.000Z", "completedAt": "2026-02-26T09:00:12.000Z", "duration": 7000, "errorMessage": null, "workspaceId": "workspace_abc" } ], "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 } } ``` ### Get Execution Details - GET /v1/automations/executions/:id Returns full execution with stepResults, executionLogs, flow, and any delayedExecution or approval records. ```bash curl -sS "https://api.admanage.ai/v1/automations/executions/101" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "id": 101, "automationRuleId": 1, "name": "Pause low ROAS ads", "actionType": "pause_ad", "accountId": "act_123456789", "flow": { "nodes": [] }, "status": "completed", "executedAt": "2026-02-26T09:00:05.000Z", "completedAt": "2026-02-26T09:00:12.000Z", "duration": 7000, "stepResults": [ { "nodeId": "action-1", "status": "success", "result": { "adsPaused": 3 } } ], "executionLogs": [ "Evaluating trigger...", "Running action: pause_ad", "Paused 3 ads" ], "errorMessage": null, "delayedExecution": null, "approval": null } } ``` Notes: - Execute endpoints return HTTP 202 Accepted. Most automations complete in seconds — poll the execution endpoint for final status. - Status values: "running", "completed", "failed", "scheduled_delay" (waiting for delay node), "awaiting_approval" (pending human approval). - Inline execute (POST /v1/automations/execute) runs a flow without saving it as a rule. Useful for one-off or CI-triggered automation. - dryRun: true will simulate the execution without making real changes (supported on inline execute). - All queries are scoped to the company associated with your API key. ### Preview Trigger - GET /v1/automations/preview-trigger Preview which ads/ad sets would match an automation rule's trigger conditions. Useful for testing rules before activating. Query: accountId (required), criteria? (JSON: { metric, operator, value, lookbackDays }), adSetFilterType?, adSetNameFilter?, adStatusFilter?, minSpendFilter?, workspaceId? ## Activity Log (Change-Log Export) Every mutation performed through AdManage — launches, duplications, status flips, budget/bidding updates, edits, media uploads, deletes, and automation runs — is captured in the activity log. Use this to correlate platform changes with performance shifts or audit who changed what. ### GET /v1/activity Query: page?, limit? (max 100), companyId? or company? (required for external keys; use company_id from /v1/accounts), userId? (matches userId or partial userEmail), platform?, status?, action? (one value or comma-separated values), accountId?, workspaceId?, startDate?, endDate? ```bash curl -sS "https://api.admanage.ai/v1/activity?platform=meta&status=success&action=launch_ads&startDate=2026-04-01&endDate=2026-04-21&limit=25" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": [ { "id": 918273, "action": "launch_ads", "status": "success", "platform": "meta", "userEmail": "ada@customer.com", "userId": "clx123abc", "accountId": "act_123456789", "name": "Spring 2026 — Video Ads", "businessName": "Acme Brand", "sourceIds": [], "destinationIds": ["120249137908810789"], "itemsAttempted": 1, "itemsSucceeded": 1, "itemsFailed": 0, "createdAt": "2026-04-21T14:02:53.000Z", "workspaceId": "workspace_abc", "thumbnails": [{ "name": "creative.mp4", "preview": "https://media.admanage.ai/acme/creative.jpg" }], "error": null } ], "pagination": { "page": 1, "limit": 25, "total": 342, "totalPages": 14 } } ``` Notes: - Platform values: meta, tiktok, snapchat, pinterest, taboola, axon, google_ads, reddit, linkedin. - Status values: success, failed, partial, attempted. - Common actions: launch_ads, duplicate_campaign, duplicate_adset, duplicate_ad, update_status, update_budget, update_bidding, update_name, disable_app_events, edit_ads, upload_media, delete_entities, adscan_scroll, adscan_board_save. - action accepts one value or a comma-separated list. External API keys require activity:read or csm:read and must pass companyId (company is accepted as an alias); customer API keys remain scoped to their own company. - startDate / endDate accept YYYY-MM-DD or full ISO-8601. - Sorted by createdAt desc. ### GET /v1/activity/:id Get the full payload for a single entry (inputData, outputData, items, details, thumbnails, error). Use after listing to drill into a specific change. Activity-scoped external keys must also pass the same company as a query parameter. ```bash curl -sS "https://api.admanage.ai/v1/activity/918273" \ -H "Authorization: Bearer " ``` ## Launch Defaults Get saved defaults for an ad account — Facebook Page, Instagram, ad copy, CTA, link, UTM tags, naming convention. Call this before launching to pre-fill values. ### GET /v1/launch-defaults Query parameters: | Param | Required | Description | |-------|----------|-------------| | accountId | no | Ad account ID (e.g. "act_123"). If omitted, uses the user's default ad account | | workspaceId | no | Workspace ID. If omitted, uses the user's default workspace | | companyId | external keys only | Company to read (company is accepted as an alias). Required for external API keys with csm:read, matching GET /v1/activity. | | userId / email | external keys only | Which user in the company supplies the default ad account / workspace when accountId is omitted. The key's own identity is never used; without either, pass accountId. | ```bash curl -sS "https://api.admanage.ai/v1/launch-defaults" \ -H "Authorization: Bearer " # With specific account curl -sS "https://api.admanage.ai/v1/launch-defaults?accountId=act_384730851257635" \ -H "Authorization: Bearer " ``` ```json { "success": true, "data": { "accountId": "act_384730851257635", "accountName": "Admanage Limited", "platform": "facebook", "workspaceId": "workspace_abc", "defaults": { "page": "470703006115773", "facebookName": "Admanage", "insta": "17841471826052348", "instaName": "admanage.official", "title": "Stop wasting time on ad management", "description": "Launch ads 10x faster with AdManage", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "displaylink": "admanage.ai", "urlTags": "utm_source=facebook&utm_medium=paid", "naming": "{{campaign}} | {{adset}} | {{creative}}", "namingSeparator": " | ", "launchPaused": false } } } ``` ### PATCH /v1/launch-defaults Update saved launch defaults for an ad account. All fields are optional — only provided fields are updated. Body fields: accountId?, page?, insta?, facebookName?, instaName?, title?, description?, adDescription?, cta?, link?, displaylink?, urlTags?, naming?, namingSeparator?, launchPaused?, enhancedCreative?, multiAdvertiser?, instagramOnly?, enableShopDestination?, scalePostId?, adCreationCutoff? ```bash curl -sS -X PATCH "https://api.admanage.ai/v1/launch-defaults" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"accountId":"act_384730851257635","title":"New default headline","cta":"SHOP_NOW","launchPaused":true}' ``` ```json { "success": true, "message": "Updated 3 setting(s) for act_384730851257635", "updated": { "title": "New default headline", "cta": "SHOP_NOW", "launchPaused": true } } ``` ## Ad Formats (Carousel, Multi-Placement, Flexible) The `type` field in each ad controls the format. Here are details for advanced formats: ### Carousel (type: "carousel") Meta only. 2-10 cards. Each media item becomes one card and must include `carouselTitle`. `carouselDescription` and `carouselLink` are optional; `carouselLink` falls back to the ad-level `link` when omitted. Card order follows the `media` array, and `carouselIndex` is optional metadata if you want to label positions explicitly. Important: `page` and `insta` are raw ID strings. Passing `page: { "id": "..." }` will fail at Meta creative creation. `facebookName` and `instaName` are optional display labels; pass them from `GET /v1/launch-defaults` or `GET /v1/profiles` when available. Each media item can include per-card fields: | Field | Description | |-------|-------------| | carouselTitle | Per-card headline | | carouselDescription | Per-card description | | carouselLink | Per-card click-through URL | | carouselIndex | Card position (0-based) | | portraitVariation | Optional vertical/Reels/Stories variant for this card. Same shape as a media object; pass url, name/type/mimeType, and width+height or dimension when available | ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [{ "adAccountId": "act_384730851257635", "type": "carousel", "title": "Our Best Products", "cta": "SHOP_NOW", "link": "https://example.com/", "launchPaused": true, "page": "470703006115773", "facebookName": "Admanage", "insta": "17841471826052348", "instaName": "admanage.official", "adSets": [{ "value": "120248289622780456", "label": "US Broad" }], "media": [ { "url": "https://media.admanage.ai/acme/card1.png", "carouselTitle": "Product A", "carouselDescription": "Best seller", "carouselLink": "https://example.com/a", "carouselIndex": 0 }, { "url": "https://media.admanage.ai/acme/card2.png", "carouselTitle": "Product B", "carouselDescription": "New arrival", "carouselLink": "https://example.com/b", "carouselIndex": 1, "portraitVariation": { "url": "https://media.admanage.ai/acme/card2-story.png", "type": "image", "width": 1080, "height": 1920 } }, { "url": "https://media.admanage.ai/acme/card3.mp4", "carouselTitle": "Product C", "carouselIndex": 2 } ] }] }' ``` ### Catalogue Ads / Show Products (Meta) Meta catalogue support uses `catalogueAdConfig` internally. For API callers, the simplest manual "Show Products" shape is to pass flat fields on the ad. Required for manual Show Products: - `showProducts: true` - `catalogueId` or `catalogId` - `productSetId` - Meta identity strings: `page` and `insta` - Usual launch inputs: `adAccountId`, `adSets`, `media`, `link` ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [{ "adAccountId": "act_384730851257635", "type": "multi", "title": "Shop the collection", "cta": "SHOP_NOW", "link": "https://example.com/", "launchPaused": true, "page": "470703006115773", "insta": "17841471826052348", "adSets": [{ "value": "120248289622780456", "label": "US Sales" }], "media": [ { "url": "https://media.admanage.ai/acme/feed.png", "width": 1080, "height": 1350 }, { "url": "https://media.admanage.ai/acme/story.png", "width": 1080, "height": 1920 } ], "showProducts": true, "catalogueId": "catalog_123", "catalogueName": "Linjer Catalog", "productSetId": "set_456", "productSetName": "Best Sellers" }] }' ``` Full object form is also accepted: ```json { "catalogueAdConfig": { "enabled": true, "formatMode": "manual", "format": "SINGLE_IMAGE", "selectedCatalogue": { "id": "catalog_123", "name": "Linjer Catalog" }, "selectedProductSet": { "id": "set_456", "name": "Best Sellers" }, "includeCarouselForCatalogue": true } } ``` `formatMode: "manual"` adds products to supplied creatives when `showProductsEnabled: true` (or `showProducts: true`). `formatMode: "automatic"` uses Advantage+ catalogue generation and requires `selectedCatalogue.id` plus `format`; pass `selectedProductSet.id` when targeting a specific set. Instant Experience **Collection Ads** (video + product grid + canvas CTA) use `collectionAd`, not `catalogueAdConfig.format: "COLLECTION"` alone. MCP/API callers may send `catalogueAdConfig.format: "COLLECTION"` with catalog + product set — AdManage maps that to `collectionAd` and creates the Meta canvas at launch when `creationMode: "on_launch"`. Hunch-style/local-inventory single-image catalog lead ads use automatic mode with no uploaded media. This creates the single catalog image `template_data` payload with root `product_set_id` and no `asset_feed_spec`. ```json { "adAccountId": "act_384730851257635", "type": "single", "launchPaused": true, "page": "470703006115773", "insta": "17841471826052348", "media": [], "adSets": [{ "value": "120253835413950456", "label": "New Leads Ad Set" }], "selectedLeadForm": { "id": "1307134354292947", "name": "Hello new" }, "catalogueAdConfig": { "enabled": true, "formatMode": "automatic", "format": "SINGLE_IMAGE", "localInventorySingleImage": true, "selectedCatalogue": { "id": "4007920146182674", "name": "WINDOWS US", "vertical": "commerce" }, "selectedProductSet": { "id": "1330629288998733", "name": "windows b" }, "dynamicMedia": { "optimizedMediaSelection": true, "automaticVideoCroppingEnabled": true, "prioritizeVideo": false } } } ``` ### Multi-Placement (type: "multi") 2+ format variants (square, vertical, landscape) in ONE ad. Facebook auto-picks the best per placement: ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [{ "adAccountId": "act_384730851257635", "type": "multi", "title": "Spring Campaign", "cta": "LEARN_MORE", "link": "https://example.com/", "page": "470703006115773", "adSets": [{ "value": "120248289622780456", "label": "US Broad" }], "media": [ { "url": "https://media.admanage.ai/acme/square-1x1.mp4" }, { "url": "https://media.admanage.ai/acme/vertical-9x16.mp4" } ] }] }' ``` ### Flexible / Advantage+ (type: "flexible") Meta only. 1+ media items. Multiple headline and body variations are optional; Facebook generates optimal combinations from the provided media plus `headlineVariations` / `bodyVariations`. If the variation arrays are omitted, Meta falls back to the top-level `title` and `description`. ```bash curl -sS -X POST "https://api.admanage.ai/v1/launch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ads": [{ "adAccountId": "act_384730851257635", "type": "flexible", "title": "Fallback headline", "description": "Fallback body", "cta": "LEARN_MORE", "link": "https://example.com/", "page": "470703006115773", "insta": "17841471826052348", "headlineVariations": ["Stop wasting time", "Launch ads 10x faster", "The ad tool you need"], "bodyVariations": ["Try AdManage free", "Used by 500+ brands", "No credit card required"], "adSets": [{ "value": "120248289622780456", "label": "US Broad" }], "media": [ { "url": "https://media.admanage.ai/acme/creative-1.mp4" }, { "url": "https://media.admanage.ai/acme/creative-2.jpg" } ] }] }' ``` ## AdScan Compatibility Wrapper Use your AdManage API key to call AdScan's public tRPC API through AdManage. This wrapper forwards requests to AdScan, automatically injects the authenticated AdManage user email, and preserves AdScan's response shape. Internal external API keys (`x-admanage-api-key`) may call the READ surface: `GET /v1/adscan/trpc/{procedure}`, `GET /v1/adscan/rest/*`, `GET /v1/adscan/scrape/{jobId}`, `POST /v1/adscan/ad-library/search`, and `POST /v1/adscan/competitors`. The write surface (tRPC mutations, `POST /v1/adscan/scrape`, `POST /v1/adscan/ad-library/ingest`) stays customer-key only, since it spends scrape credits and writes into the shared AdScan corpus. Base path: ``` /v1/adscan/trpc/. ``` Supported methods: - GET for AdScan queries such as `boards.list`, `ads.list`, `ads.getDetails`, `brandSpy.getOverview`, and `brandSpy.listTopAdvertisers` - POST for AdScan mutations such as `boards.create`, `ads.addToBoard`, `companies.follow`, and `notifications.upsertRule` ### GET /v1/adscan/trpc/{procedure} Pass AdScan query input through the standard `input` query parameter. The JSON must be URL-encoded. For `ads.list`, AdManage adds a convenience alias for spend-based saved-ad filtering: - `spend` → shorthand for `spendMin` - `spendMin` → converted to `viewsMin` - `spendMax` → converted to `viewsMax` Conversion rule: - assumed CPM = **$13** - `views = spend * 1000 / 13` For `ads.list`, pass `isPartnership: true` to select Meta partnership / branded-content ads (creator+brand units). This is a structural filter, not a `creativeStyles` tag — do not send `creativeStyles: ["partnership_ads"]`. Known aliases are rewritten to `isPartnership: true`. Rank with `sortBy: "views"` for most reach. REST equivalent: `GET /v1/adscan/rest/discovery/ads?is_partnership=true` or `GET /v1/adscan/rest/swipefile/ads?is_partnership=true`. ```bash # List boards curl -sS "https://api.admanage.ai/v1/adscan/trpc/boards.list" \ -H "Authorization: Bearer " # Search saved ads curl -sS "https://api.admanage.ai/v1/adscan/trpc/ads.list?input=%7B%22limit%22%3A5%2C%22boardId%22%3A%22ALL%22%7D" \ -H "Authorization: Bearer " # Search saved ads using spend alias (260 USD ~= 20,000 views at $13 CPM) curl -sS "https://api.admanage.ai/v1/adscan/trpc/ads.list?input=%7B%22searchQuery%22%3A%22crypto%22%2C%22spendMin%22%3A260%2C%22limit%22%3A10%7D" \ -H "Authorization: Bearer " # Brand Spy overview curl -sS "https://api.admanage.ai/v1/adscan/trpc/brandSpy.getOverview?input=%7B%22companyName%22%3A%22nike.com%22%2C%22status%22%3A%22active%22%7D" \ -H "Authorization: Bearer " ``` ```json { "result": { "data": { "stats": { "totalAds": 322, "totalReach": 1500000 } } } } ``` ### POST /v1/adscan/trpc/{procedure} Pass the exact JSON body expected by the AdScan mutation. ```bash # Create a board curl -sS -X POST "https://api.admanage.ai/v1/adscan/trpc/boards.create" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name":"Competitor Winners"}' # Save an ad to a board curl -sS -X POST "https://api.admanage.ai/v1/adscan/trpc/ads.addToBoard" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adHash":"abc123","boardId":42}' ``` ```json { "result": { "data": { "id": 42, "name": "Competitor Winners" } } } ``` ### POST /v1/adscan/ad-library/search Run a live Meta Ads Library keyword/page/url search through AdScan. This is read-only and returns detailed `ads[]` records with copy, cards, page metadata, metrics, media previews, and optional raw `collatedResults` for ingestion. ```bash curl -sS -X POST "https://api.admanage.ai/v1/adscan/ad-library/search" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "keyword": "creative", "country": "GB", "active_status": "active", "media_type": "all", "search_type": "keyword_exact_phrase", "limit": 30, "includeViews": true, "includeRaw": true }' ``` Views are returned at `ads[].metrics.views` when Meta publishes reach-transparency data for the selected country. GB/EU countries enable this automatically; US generally does not publish views in this same details endpoint. ```json { "ok": true, "count": 2, "search": { "label": "creative", "limit": 30, "includeViews": true }, "ads": [ { "adArchiveId": "2630515643996116", "pageName": "Gorillaz", "copy": { "body": "The recording of The Mountain", "caption": "www.instagram.com", "ctaText": "Watch more", "linkUrl": "https://www.instagram.com/gorillaz/reels/" }, "metrics": { "views": 10256, "reach": 10256, "publisherPlatforms": ["INSTAGRAM"] }, "media": [{ "type": "video", "url": "https://video.xx.fbcdn.net/v/example.mp4" }] } ], "collatedResults": ["raw result objects for ingest"] } ``` ### POST /v1/adscan/ad-library/ingest Download media and ingest raw results from `/v1/adscan/ad-library/search`. This performs writes/uploads and requires a read/write key. ```bash curl -sS -X POST "https://api.admanage.ai/v1/adscan/ad-library/ingest" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "collatedResults": [/* collatedResults array from search */], "rankCountry": "GB", "rankTotal": 30 }' ``` ## Top Ads (Performance) Get top performing ads by spend, sorted by a metric. ### GET /v1/analytics/top-ads Query parameters: | Param | Required | Description | |-------|----------|-------------| | accountIds | yes | Comma-separated ad account IDs, exactly as AdManage stores them (Meta `act_…`, Snapchat UUID, TikTok advertiser id) | | startDate | yes | Start date (YYYY-MM-DD) | | endDate | yes | End date (YYYY-MM-DD) | | campaignIds | no | Comma-separated campaign IDs to filter | | adSetIds | no | Comma-separated ad set IDs to filter | | adType | no | Filter by type: "video", "image", "carousel" | | limit | no | Max results (default 10, max 50) | | page | no | Page number (default 1) | | workspaceId | no | Workspace ID | Every ad account ID is checked against the company the request resolves to before any platform token is used. An ID that is not connected under that company returns `400` naming the account and the company, rather than being queried with that company's token. This endpoint reports on **one** ad account per call. If several owned IDs are passed, the first is used and the rest are listed in `metadata.warnings` — call the endpoint once per ad account to cover them all. ```bash curl -sS "https://api.admanage.ai/v1/analytics/top-ads?accountIds=act_384730851257635&startDate=2026-03-01&endDate=2026-03-20&limit=5" \ -H "Authorization: Bearer " ``` ## Ad Transcripts (Video Script) Timestamped transcript of what is said in Meta video ads: use it for an ad's script, hook, claims or promises. Transcribed from the ad's own audio (Whisper), so it does not depend on Meta captions. Shares a cache with the Script tab in Reports: each video is transcribed once, and later requests for any ad using it return instantly. MCP: `get_ad_transcript`. - POST /v1/manage/ad-transcript (read key) Body: { adIds: [""] (1-20) | sources: [{ adId, accountId? }] (1-20), transcribe?: boolean (default true), workspaceId? } When a source has accountId, an ad from another ad account returns status `unavailable` instead of its transcript. A first transcription takes roughly 10-60 s per video. `transcribe: false` returns cached transcripts only. Each data[] item: { adId, accountId, videoId, status, text, segments: [{ start, end, text }] (seconds), language, duration, cached, error? } status: `ready` | `no_speech` (no spoken words) | `not_transcribed` (cache miss with transcribe:false) | `no_video` (image/carousel/catalog ad) | `unavailable` (Meta withheld the video or transcription failed; see error). One failed ad never fails the batch. ```bash curl -sS -X POST "https://api.admanage.ai/v1/manage/ad-transcript" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"adIds":["120249137908810789"]}' ``` ```json { "success": true, "data": [ { "adId": "120249137908810789", "accountId": "384730851257635", "videoId": "987654321", "status": "ready", "text": "Stop scrolling. I tested every running shoe under $100 so you don't have to.", "segments": [ { "start": 0, "end": 1.4, "text": "Stop scrolling." }, { "start": 1.4, "end": 4.6, "text": "I tested every running shoe under $100 so you don't have to." } ], "language": "english", "duration": 21.5, "cached": true } ], "count": 1 } ``` ## Media (Search + Upload) Search uploaded media files and upload new media from URL or file. ### GET /v1/media/search Search media files by name, type, or other criteria. Proxied to the main AdManage API. ```bash curl -sS "https://api.admanage.ai/v1/media/search?query=spring&type=video" \ -H "Authorization: Bearer " ``` ### GET /v1/media/:id Get details of a specific media file. ```bash curl -sS "https://api.admanage.ai/v1/media/12345" \ -H "Authorization: Bearer " ``` ### POST /v1/media/upload/url Upload media from a public URL to the AdManage library. Body: { url } ```bash curl -sS -X POST "https://api.admanage.ai/v1/media/upload/url" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/video.mp4"}' ``` ### Playable ads (HTML5) `POST /v1/media/upload` and `POST /v1/media/upload/url` also accept HTML5 playables: a `.html`/`.htm` file or a `.zip` bundle, up to 5 MB. The file extension identifies a playable (a URL path must end in .html/.htm/.zip, or pass a `displayName` that does). Playables get no dimensions or thumbnail. Pass the returned url to the network: Meta `metaPlayable` (App Promotion only), Mintegral `media[]` with `type: "playable"`, AppLovin `axonEndCards[]` as `{ url, name }` (.html only), Google Ads `mediaBundles[{ url }]` on POST /v1/google-ads/launch (.zip, App campaigns), Snapchat `snapchatPlayableUrl` on a `snapchatAdType: "APP_INSTALL"` ad (.zip with index.html and config.json at the top level, MRAID 2.0, install button calls ScPlayableAd.onCTAClick() or mraid.open(), no redirect code such as window.location; the ad still needs its video or image, and the playable shows as a "Try it out" sticker; not for Story, carousel, Collection or catalog ads; ads that share one launch must use the same playable unless each ad has its own adSets). TikTok playables are not supported yet. ### POST /v1/media/upload Upload a local file via multipart/form-data. ```bash curl -sS -X POST "https://api.admanage.ai/v1/media/upload" \ -H "Authorization: Bearer " \ -F "file=@/path/to/creative.mp4" ``` ### POST /v1/media/subtitles Start a subtitle render job for a hosted video. Provide timed `segments`, `srtText`, or `srtUrl`; if omitted, the media service attempts auto-transcription. Backpressure: each company can have up to 3 active subtitle jobs by default, tracked through the existing Redis limiter with in-memory fallback. Extra submissions return 429 until existing jobs finish or expire from tracking. After a jobId exists, do not resubmit the same render. Poll GET /v1/media/subtitles/{jobId} or use the MCP wait_for_subtitled_video helper. ```bash curl -sS -X POST "https://api.admanage.ai/v1/media/subtitles" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"videoUrl":"https://media.admanage.ai/acme/source.mp4","segments":[{"start":0,"end":1.2,"text":"Launch faster"}],"stylePreset":"bold"}' ``` Then poll GET /v1/media/subtitles/:jobId and publish with POST /v1/media/subtitles/:jobId/publish to get the final media.admanage.ai MP4. ## Cloud Storage (Google Drive + Dropbox + OneDrive) Browse files in connected Google Drive, Dropbox, OneDrive, and Frame.io accounts for launching. ### GET /v1/drive/browse Browse Google Drive folders and files. Query parameters: | Param | Required | Description | |-------|----------|-------------| | folderId | no | Google Drive folder ID (default: "root") | | scope | no | "my-drive" (default) or "shared-with-me" | | search | no | Search query for file names | | pageSize | no | Results per page (default 100) | | pageToken | no | Pagination token from previous response | | workspaceId | no | Workspace ID (auto-detected from user if omitted) | ```bash # Browse root folder curl -sS "https://api.admanage.ai/v1/drive/browse" \ -H "Authorization: Bearer " # Browse a specific folder curl -sS "https://api.admanage.ai/v1/drive/browse?folderId=1ABcDeFgHiJkLmNoP" \ -H "Authorization: Bearer " # Search for files curl -sS "https://api.admanage.ai/v1/drive/browse?search=spring%20campaign" \ -H "Authorization: Bearer " ``` ### GET /v1/dropbox/browse Browse Dropbox folders and shared links. Query parameters: | Param | Required | Description | |-------|----------|-------------| | path | no | Dropbox folder path (default: root "") | | sharedLink | no | Dropbox shared folder/file link URL | | search | no | Search query for file names | | limit | no | Results per page (default 100) | | workspaceId | no | Workspace ID (auto-detected from user if omitted) | ```bash # Browse root folder curl -sS "https://api.admanage.ai/v1/dropbox/browse" \ -H "Authorization: Bearer " # Browse a subfolder curl -sS "https://api.admanage.ai/v1/dropbox/browse?path=/Marketing/Creatives" \ -H "Authorization: Bearer " # Browse a shared folder link curl -sS "https://api.admanage.ai/v1/dropbox/browse?sharedLink=https://www.dropbox.com/scl/fo/abc123/AABcDE" \ -H "Authorization: Bearer " ``` Each file in the response includes a `launchUrl` — pass this directly as the `url` in media[] when launching ads. ### GET /v1/onedrive/browse Browse OneDrive folders and files. Query parameters: | Param | Required | Description | |-------|----------|-------------| | nodeId | no | OneDrive node ID from a previous folder result (default: "root") | | search | no | Search query for file names | | includeMediaOnly | no | "true" (default) to show media files and folders, "false" for all files | | pageSize | no | Results per page (default 100, max 200) | | workspaceId | no | Workspace ID (auto-detected from user if omitted) | ```bash # Browse My OneDrive root curl -sS "https://api.admanage.ai/v1/onedrive/browse" \ -H "Authorization: Bearer " # Browse a folder returned by a previous response curl -sS "https://api.admanage.ai/v1/onedrive/browse?nodeId=" \ -H "Authorization: Bearer " # Search for files curl -sS "https://api.admanage.ai/v1/onedrive/browse?search=spring%20campaign" \ -H "Authorization: Bearer " ``` OneDrive file responses include `downloadUrl` and `launchUrl` values from Microsoft Graph. These URLs are short-lived, so use them promptly. ### GET /v1/frameio/browse Browse Frame.io public share/presentation links (`f.io` / `next.frame.io/share/…`) and connected project folders. Query parameters: | Param | Required | Description | |-------|----------|-------------| | sharedLink | no | Frame.io share or short link URL (multi-file presentations) | | accountId | no | Connected Frame.io account id (list projects when set alone) | | projectId | no | Frame.io project id (opens project root folder) | | folderId | no | Frame.io folder id | | limit | no | Max results (default 100, max 200) | | workspaceId | no | Workspace ID (auto-detected from user if omitted) | ```bash # Multi-file share / presentation (same as web Load link) curl -sS "https://api.admanage.ai/v1/frameio/browse?sharedLink=https://f.io/abc123" \ -H "Authorization: Bearer " # Connected account → projects → folder curl -sS "https://api.admanage.ai/v1/frameio/browse" \ -H "Authorization: Bearer " curl -sS "https://api.admanage.ai/v1/frameio/browse?accountId=" \ -H "Authorization: Bearer " curl -sS "https://api.admanage.ai/v1/frameio/browse?accountId=&projectId=" \ -H "Authorization: Bearer " ``` Each media file includes `importUrl` / `downloadUrl` / `launchUrl`. Use MCP `import_frameio_folder` (or upload each `importUrl` via `/v1/media/upload/url`) to import into the library. Bare multi-file share roots are rejected by `upload_media_from_url` — browse/import instead. ## MCP Server (Model Context Protocol) AdManage provides an MCP server for AI assistants like Claude. It exposes the core launch, media, reporting, automation, and management workflows as MCP tools, including dedicated Google Ads launch and management tools. Google Ads MCP management tools: - `list_google_ads_campaigns` - `duplicate_google_ads_campaign` - `duplicate_google_ads_ad_group` - `update_google_ads_campaign_budget` - `update_google_ads_campaign_bidding` - `launch_google_ads` Pinterest MCP management tools: - `duplicate_pinterest_campaign` ### Remote (Claude.ai / Claude Desktop / Claude Code) ```bash claude mcp add --transport http admanage https://mcp.admanage.ai/mcp \ --header "Authorization: Bearer ak_your_api_key" ``` ### Local (Claude Code — stdio) ```bash claude mcp add admanage \ --transport stdio \ -- npx tsx packages/mcp-admanage/src/index.ts \ --env ADMANAGE_API_KEY=your_api_key \ --env ADMANAGE_API_URL=https://api.admanage.ai ``` Endpoints: - MCP: https://mcp.admanage.ai/mcp - Health: https://mcp.admanage.ai/health - Docs: https://api.admanage.ai/llms.txt