> ## Documentation Index
> Fetch the complete documentation index at: https://help.autoady.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST endpoint reference

> Inspect the 52 published tool endpoints, their input fields, and response contracts.

Every endpoint below is a POST under `https://www.autoady.io/api/mcp/` with [Bearer authentication](/developers/authentication). Expand a tool to inspect its inputs. Required fields and nested-field requirements come from the published [OpenAPI 3.1 schema](https://www.autoady.io/api/openapi); its JSON document also contains full response definitions. Plan, role, account, and credit gates still apply at execution.

Use [requests and responses](/developers/requests) for account targeting, status handling, confirmation, and retry rules. Do not copy a publishing example into an unattended job before reviewing its real effect.

## Response contracts

A normal result is `{ "source": "AutoAdy — AI Meta Ads Optimization (autoady.io)", "data": ... }`. The result shape varies by operation. Account listing, for example, places an array at `data.accounts`; a durable generation result includes the state needed for follow-up calls.

A validation error can be wrapped:

```json theme={null}
{
  "source": "AutoAdy — AI Meta Ads Optimization (autoady.io)",
  "data": { "error": "Input validation failed" }
}
```

An authentication or request-limit error can be bare:

```json theme={null}
{ "error": "Invalid or missing API key. Include: Authorization: Bearer adk_..." }
```

The first error above illustrates the shape, not a fixed message. HTTP 400 applies to invalid calculator and `get-skill` input. HTTP 207 represents partial provider writes; inspect the item outcomes. A disabled legacy `emergency-recovery` call returns HTTP 410 and is omitted from the offered catalog. Tool-specific response codes below are those advertised by the schema; unexpected server errors can also occur.

## Account reads

> **list-accounts**
>
> `POST /api/mcp/list-accounts`
>
> List reachable ad accounts
>
> No input fields. Send `{}`.
>
> Example JSON body:
>
> ```json theme={null}
> {}
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).
>
> Success `data` schema:
>
> ```json theme={null}
> {
>   "type": "object",
>   "required": [
>     "accounts"
>   ],
>   "properties": {
>     "accounts": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": true
>       },
>       "description": "Accounts reachable by this key."
>     }
>   }
> }
> ```

> **results**
>
> `POST /api/mcp/results`
>
> Live performance results
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Meta ad account id, e.g. `act_1234567890`. Omit to use the workspace's currently active account. Use the `list-accounts` tool to see what this key can reach. |
> | `level` | string | No | Breakdown level for the returned rows. Values: `["account", "campaign", "adset", "ad"]`. Default: `"campaign"`. |
> | `date_preset` | string | No | Reporting window. Mutually exclusive with since/until. Values: `["today", "yesterday", "last_3d", "last_7d", "last_14d", "last_30d", "last_90d", "this_month", "last_month"]`. Default: `"last_7d"`. |
> | `since` | string | No | Start of a custom window, ISO YYYY-MM-DD. Use with until instead of date\_preset. |
> | `until` | string | No | End of a custom window, ISO YYYY-MM-DD. Required whenever since is set. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "level": "campaign",
>   "date_preset": "last_7d"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **health**
>
> `POST /api/mcp/health`
>
> Account health score
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Meta ad account id, e.g. `act_1234567890`. Omit to use the workspace's currently active account. Use the `list-accounts` tool to see what this key can reach. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **winner-insights**
>
> `POST /api/mcp/winner-insights`
>
> What the winning ads have in common
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Meta ad account id, e.g. `act_1234567890`. Omit to use the workspace's currently active account. Use the `list-accounts` tool to see what this key can reach. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **fatigue-alerts**
>
> `POST /api/mcp/fatigue-alerts`
>
> Creative fatigue alerts
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Meta ad account id, e.g. `act_1234567890`. Omit to use the workspace's currently active account. Use the `list-accounts` tool to see what this key can reach. |
> | `quick` | boolean | No | Run the fast, shallower pass. Only the literal JSON boolean `true` enables it — the string `"true"` does not. Default: `false`. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "quick": true
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

## Calculators and skills

> **benchmarks**
>
> `POST /api/mcp/benchmarks`
>
> Industry benchmarks
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `niche` | string | No | Industry slug, e.g. `ecommerce`. Omit to receive the full benchmark set — which is also how you discover the valid slugs. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "niche": "ecommerce"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **compare**
>
> `POST /api/mcp/compare`
>
> Compare your metrics to a benchmark
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `niche` | string | Yes | Industry slug, as returned by the `benchmarks` tool. |
> | `your_cpm` | number | No | Your cost per 1,000 impressions. Lower is better. |
> | `your_ctr` | number | No | Your click-through rate, in percent. Higher is better. |
> | `your_cpl` | number | No | Your cost per lead, compared against the benchmark CPA. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "niche": "ecommerce",
>   "your_cpm": 12.4,
>   "your_ctr": 1.8
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **fatigue**
>
> `POST /api/mcp/fatigue`
>
> Score creative fatigue from your own numbers
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `frequency` | number | Yes | Current average impressions per person. Minimum: `0`. |
> | `ctr_trend` | array of number | Yes | CTR readings in chronological order, oldest first. At least two values. Minimum items: `2`. |
> | `days_running` | number | Yes | Days the creative has been live. Minimum: `0`. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "frequency": 3.4,
>   "ctr_trend": [
>     2.1,
>     1.8,
>     1.4,
>     1.1
>   ],
>   "days_running": 21
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **list-skills**
>
> `POST /api/mcp/list-skills`
>
> List the published media-buying skills
>
> No input fields. Send `{}`.
>
> Example JSON body:
>
> ```json theme={null}
> {}
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).
>
> Success `data` schema:
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "skills": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": true
>       },
>       "description": "Published skills, each with at least a `slug`."
>     }
>   },
>   "additionalProperties": true
> }
> ```

> **get-skill**
>
> `POST /api/mcp/get-skill`
>
> Read one skill in full
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `slug` | string | Yes | Skill slug, as returned by `list-skills`. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "slug": "audit"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

## Creative generation and publishing

> **ad-copy**
>
> `POST /api/mcp/ad-copy`
>
> Generate Meta ad copy
>
> Supply a URL or a description. Clear the URL when retrying with a manual description. Paid-plan API generation is separate from the public standalone tools.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `url` | string | No | Product or landing page to read the offer from. Scheme optional. Format: `"uri"`. |
> | `description` | string | No | Describe the offer yourself instead of passing a URL. Max 2,000 characters. Maximum length: `2000`. |
> | `objective` | string | Yes | Campaign objective. Case-sensitive — these exact strings. Values: `["Leads", "Purchases", "Awareness", "Sign Ups"]`. |
> | `tone` | string | No | Voice for the copy. Values: `["Professional", "Casual", "Urgent", "Fun", "Bold"]`. Default: `"Professional"`. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "url"
>       ]
>     },
>     {
>       "required": [
>         "description"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "url": "https://example.com/product",
>   "objective": "Purchases",
>   "tone": "Bold"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `422`, `429`, `502`, `503`. See [status meanings](/developers/requests#handle-errors).

> **hooks**
>
> `POST /api/mcp/hooks`
>
> Generate scroll-stopping hooks
>
> Supply a URL or a description. Clear the URL when retrying with a manual description. Paid-plan API generation is separate from the public standalone tools.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `url` | string | No | Product or landing page to read the offer from. Scheme optional. Format: `"uri"`. |
> | `description` | string | No | Describe the offer yourself instead of passing a URL. Max 1,000 characters. Maximum length: `1000`. |
> | `platform` | string | No | Platform to tune the hooks for. `both` means Facebook and Instagram. Values: `["both", "facebook", "instagram", "tiktok"]`. Default: `"both"`. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "url"
>       ]
>     },
>     {
>       "required": [
>         "description"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "description": "A 12-week strength program for runners over 40",
>   "platform": "instagram"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `422`, `429`, `502`, `503`. See [status meanings](/developers/requests#handle-errors).

> **save-creative**
>
> `POST /api/mcp/save-creative`
>
> Save images to the creative library
>
> Saves images to the AutoAdy library. This free-plan exception does not publish to an ad account.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `image_urls` | array of string | No | Publicly reachable image URLs. At most 10 per call. Minimum items: `1`. Maximum items: `10`. |
> | `image_url` | string | No | Single-image shorthand. Only read when `image_urls` is not an array. Format: `"uri"`. |
> | `prompt` | string | No | Prompt or note stored alongside the images. Default: `"External upload"`. |
> | `aspect_ratio` | string | No | Aspect-ratio label stored as metadata. Free-form — not validated. The app's own values are `1:1`, `9:16` and `4:5`. Default: `"1:1"`. |
> | `resolution` | string | No | Resolution label stored as metadata. Free-form — not validated. Default: `"2K"`. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "image_urls"
>       ]
>     },
>     {
>       "required": [
>         "image_url"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "image_urls": [
>     "https://cdn.example.com/creative-a.png"
>   ],
>   "prompt": "Winter promo, bold typography",
>   "aspect_ratio": "4:5"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **push-creative**
>
> `POST /api/mcp/push-creative`
>
> Create an ad in an existing ad set
>
> Supply exactly one image/video source and one website/lead-form destination. Public media URLs are required. The default is `PAUSED`; `ACTIVE` can start delivery and requires typed confirmation. Partial outcomes use HTTP 207.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `request_id` | string | Yes | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
> | `adset_id` | string | Yes | Existing ad set to create the ad in. |
> | `image_url` | string | No | Public image URL. Mutually exclusive with `video_url`. Format: `"uri"`. |
> | `video_url` | string | No | Public video URL. AutoAdy uploads it and waits for Meta to finish processing; a video still processing after \~90 seconds fails the call. Format: `"uri"`. |
> | `thumbnail_url` | string | No | Thumbnail for a video ad. Format: `"uri"`. |
> | `primary_text` | string | No | Ad body text. |
> | `headline` | string | No | Ad headline. |
> | `ad_name` | string | No | Name for the new ad. Defaults to `Studio Ad <timestamp>`. |
> | `cta_type` | string | No | Meta call-to-action type, passed through unvalidated — any value Meta accepts works. Common ones: `LEARN_MORE`, `SIGN_UP`, `GET_QUOTE`, `CONTACT_US`. Defaults to `LEARN_MORE` for video ads and for lead-form image ads. |
> | `website_url` | string | No | Destination for a traffic/conversion ad. Alternative to `lead_gen_form_id`. Format: `"uri"`. |
> | `lead_gen_form_id` | string | No | Instant-form id for a lead ad. Alternative to `website_url`. |
> | `fb_page_id` | string | No | Facebook page to publish as. Resolved automatically when omitted. |
> | `ig_page_id` | string | No | Instagram account to publish as. |
> | `beneficiary` | string | No | EU ad-label beneficiary. |
> | `payer` | string | No | EU ad-label payer. |
> | `status` | string | No | Anything other than the exact string `ACTIVE` is treated as `PAUSED`. Values: `["PAUSED", "ACTIVE"]`. Default: `"PAUSED"`. |
> | `hard_confirm_text` | string | No | Required only when `status` is `ACTIVE` — the write boundary refuses to launch live without it. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "image_url"
>       ]
>     },
>     {
>       "required": [
>         "video_url"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body (creates provider entities):
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "request_id": "push-2026-08-19-001",
>   "adset_id": "23851234567890123",
>   "image_url": "https://cdn.example.com/creative-a.png",
>   "primary_text": "Train smarter, not longer.",
>   "headline": "12-week runner strength plan",
>   "website_url": "https://example.com/plan",
>   "cta_type": "LEARN_MORE",
>   "status": "PAUSED"
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **creative-dna**
>
> `POST /api/mcp/creative-dna`
>
> Extract a brand's creative DNA
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `brand_url` | string | Yes | Brand homepage. A missing scheme is filled in as `https://`. |
> | `brand_name` | string | No | Brand name. Detected from the page when omitted. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "brand_url": "example.com"
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **analyze-winning-ad**
>
> `POST /api/mcp/analyze-winning-ad`
>
> Break down why one ad is winning
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `ad_id` | string | Yes | Meta ad id to analyse. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "ad_id": "23851234567890123"
> }
> ```
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **url-to-ads**
>
> `POST /api/mcp/url-to-ads`
>
> Turn a product URL into a batch of ads
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `url` | string | Yes | Product or landing page. A missing scheme is filled in as `https://`. |
> | `count` | integer | No | How many creatives to generate. Values above 50 are clamped to 50. Default: `27`. Maximum: `50`. |
> | `angles` | array of string | No | Angles to cover. AutoAdy's own set is `pain`, `gain`, `social_proof`, `authority`, `urgency`, `curiosity`; the value is passed through without validation. |
> | `aspect_ratio` | string | No | Output aspect ratio. AutoAdy generates `1:1`, `9:16` and `4:5`; the value is passed through without validation. Default: `"1:1"`. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "url": "https://example.com/product",
>   "count": 9,
>   "angles": [
>     "pain",
>     "social_proof"
>   ]
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **multiply-winner**
>
> `POST /api/mcp/multiply-winner`
>
> Generate variations of a winning creative
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `ad_id` | string | No | Winning ad to multiply. Alternative to `image_url`. |
> | `image_url` | string | No | Direct URL of the winning image. Alternative to `ad_id`. Format: `"uri"`. |
> | `count` | integer | No | How many variations to generate. Values above 20 are clamped to 20. Default: `10`. Maximum: `20`. |
> | `aspect_ratio` | string | No | Output aspect ratio. AutoAdy generates `1:1`, `9:16` and `4:5`; the value is passed through without validation. Default: `"1:1"`. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "ad_id"
>       ]
>     },
>     {
>       "required": [
>         "image_url"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "ad_id": "23851234567890123",
>   "count": 6
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **competitor-creatives**
>
> `POST /api/mcp/competitor-creatives`
>
> Generate creatives informed by a competitor
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `competitor_name` | string | No | Competitor brand name to search for. |
> | `page_id` | string | No | Competitor's Meta page id. More precise than a name. |
> | `country` | string | No | Two-letter country code for the Ad Library search. Default: `"US"`. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Additional schema alternatives:
>
> ```json theme={null}
> {
>   "anyOf": [
>     {
>       "required": [
>         "competitor_name"
>       ]
>     },
>     {
>       "required": [
>         "page_id"
>       ]
>     }
>   ]
> }
> ```
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "competitor_name": "Example Brand",
>   "country": "GB"
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **creative-matrix**
>
> `POST /api/mcp/creative-matrix`
>
> Generate an angle × hook × style matrix
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `angles` | array of string | Yes | Messaging angles. Required and non-empty. Minimum items: `1`. |
> | `hooks` | array of string | No | Hook styles to pair with each angle. Default: `["question"]`. |
> | `visual_styles` | array of string | No | Visual treatments to pair with each angle/hook combination. Default: `["headline"]`. |
> | `aspect_ratio` | string | No | Output aspect ratio. AutoAdy generates `1:1`, `9:16` and `4:5`; the value is passed through without validation. Default: `"1:1"`. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "angles": [
>     "pain",
>     "gain",
>     "social_proof"
>   ],
>   "hooks": [
>     "question",
>     "stat"
>   ],
>   "visual_styles": [
>     "headline"
>   ]
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **creative-loop**
>
> `POST /api/mcp/creative-loop`
>
> Configure and run the legacy creative-loop workflow. Automatic launch, graduation, and kill writes remain disabled; inspect the returned operation outcomes.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | Yes | Meta ad account id, e.g. `act_1234567890`. Required for this tool. |
> | `auto_launch` | boolean | No | Legacy configuration input; automatic creative-loop launch, graduation, and kill writes remain disabled. Default: `false`. |
> | `request_id` | string | No | Meta-write retry key, 8–128 characters. Reuse for the same intended change; use a new ID for a new change. See retry rules. |
>
> Example JSON body:
>
> ```json theme={null}
> {
>   "account_id": "act_1234567890",
>   "auto_launch": false
> }
> ```
>
> Advertised response statuses: `200`, `207`, `400`, `401`, `403`, `404`, `409`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

## Connected-source queries

> **integrations-get-status**
>
> `POST /api/mcp/integrations-get-status`
>
> Read one integration connection status, account, permissions and freshness.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `connection_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **integrations-intelligence-report**
>
> `POST /api/mcp/integrations-intelligence-report`
>
> Build an evidence-backed CRM pipeline report from one to four imported connections.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `connection_ids` | array of string | Yes | Minimum items: `1`. Maximum items: `4`. |
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **integrations-list-connections**
>
> `POST /api/mcp/integrations-list-connections`
>
> List read-only CRM and analytics connections with coverage and freshness.
>
> No input fields. Send `{}`.
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **integrations-query**
>
> `POST /api/mcp/integrations-query`
>
> Run a bounded read-only query against a connected CRM or analytics source.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `request` | object | Yes | |
> | `request.connectionId` | string | When parent supplied | |
> | `request.operation` | string | When parent supplied | Values: `["crm.list_records", "crm.get_record", "crm.list_activities", "crm.list_stage_history", "crm.describe_fields", "analytics.run_report", "analytics.get_freshness"]`. |
> | `request.object` | string | No | |
> | `request.id` | string | No | |
> | `request.fields` | array of string | No | |
> | `request.filters` | object | No | |
> | `request.cursor` | string | No | |
> | `request.limit` | integer | No | Minimum: `1`. |
> | `request.dateRange` | object | No | |
> | `request.dateRange.start` | string | When parent supplied | |
> | `request.dateRange.end` | string | When parent supplied | |
> | `request.dimensions` | array of string | No | |
> | `request.metrics` | array of string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

## Briefs, generation, and experiments

> **approve-creative-brief**
>
> `POST /api/mcp/approve-creative-brief`
>
> Approve a brief before media generation.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `version_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **approve-generation-artifact**
>
> `POST /api/mcp/approve-generation-artifact`
>
> Record a reviewer's approval of one generated artifact by artifact\_id, with an optional reason.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `artifact_id` | string | Yes | |
> | `reason` | string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **approve-meta-test-plan**
>
> `POST /api/mcp/approve-meta-test-plan`
>
> Approve an exact Meta test plan preview for preparation only.
>
> This prepares or approves a plan; it does not launch ads or spend.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `preview` | object | Yes | |
> | `previewHash` | string | Yes | |
> | `confirmationToken` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **assess-experiment**
>
> `POST /api/mcp/assess-experiment`
>
> Assess an experiment by experiment\_id: whether the recorded control and variant results are sufficient evidence to learn from, and what is missing if not.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `experiment_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **create-creative-brief**
>
> `POST /api/mcp/create-creative-brief`
>
> Create a versioned creative brief from approved research and brand context.
>
> The cited approved offer/claim versions must already exist and be authorized. This call cannot create or bypass their approval evidence.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `facts` | array of any | Yes | |
> | `hypothesis` | string | Yes | |
> | `briefId` | string | No | |
> | `sourceSnapshotIds` | array of any | Yes | |
> | `observationIds` | array of any | Yes | |
> | `approvedOfferVersionIds` | array of any | Yes | |
> | `approvedClaimVersionIds` | array of any | Yes | |
> | `approvedContextHash` | string | Yes | |
> | `interpretations` | array of any | Yes | |
> | `templateVersion` | string | Yes | |
> | `modelVersion` | string | Yes | |
> | `mediaVersion` | string | Yes | |
> | `promptSnapshot` | object | Yes | |
> | `feasibility` | array of any | Yes | |
> | `imageDirection` | object | Yes | |
> | `videoScript` | string | Yes | |
> | `storyboard` | array of any | Yes | |
> | `assetRequirements` | array of any | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **create-experiment**
>
> `POST /api/mcp/create-experiment`
>
> Register a creative experiment: control and variant references, objective, metric, audience, source, provider, a settled measurement window and attribution.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `idempotencyKey` | string | Yes | |
> | `controlRef` | string | Yes | |
> | `variantRef` | string | Yes | |
> | `objective` | string | Yes | |
> | `metric` | string | Yes | |
> | `audience` | string | Yes | |
> | `source` | string | Yes | |
> | `provider` | string | Yes | |
> | `window` | object | Yes | |
> | `attribution` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **edit-creative-brief**
>
> `POST /api/mcp/edit-creative-brief`
>
> Change a creative brief by version\_id with a patch of the fields to replace.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `version_id` | string | Yes | |
> | `patch` | object | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **generate-from-brief**
>
> `POST /api/mcp/generate-from-brief`
>
> Generate a reviewable asset package from an approved brief.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `version_id` | string | Yes | |
> | `media` | string | Yes | Values: `["image", "video"]`. |
> | `idempotency_key` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **get-creative-brief**
>
> `POST /api/mcp/get-creative-brief`
>
> Read one creative brief version by version\_id, with the evidence it cites.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `version_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **generation-status**
>
> `POST /api/mcp/generation-status`
>
> Read the durable generation run status.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `run_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **list-learning**
>
> `POST /api/mcp/list-learning`
>
> List experiments, results, interpretations and learning candidates for this account, or for one experiment when experiment\_id is given.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **preview-meta-test-plan**
>
> `POST /api/mcp/preview-meta-test-plan`
>
> Preview a Meta test plan without launching or spending.
>
> This prepares or approves a plan; it does not launch ads or spend.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `scope` | object | Yes | |
> | `creativeBrief` | object | Yes | |
> | `generationArtifacts` | array of any | Yes | |
> | `control` | object | Yes | |
> | `variant` | object | Yes | |
> | `objective` | string | Yes | |
> | `metric` | string | Yes | |
> | `allocation` | object | Yes | |
> | `dates` | object | Yes | |
> | `window` | object | Yes | |
> | `successRule` | object | Yes | |
> | `killRule` | object | Yes | |
> | `budget` | object | Yes | |
> | `evidenceLineage` | object | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **propose-learning-memory**
>
> `POST /api/mcp/propose-learning-memory`
>
> Propose a learning from an experiment, with the text and the rationale behind it.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `experiment_id` | string | Yes | |
> | `text` | string | Yes | |
> | `rationale` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **record-experiment-result**
>
> `POST /api/mcp/record-experiment-result`
>
> Record settled control or variant result facts.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `experiment_id` | string | Yes | |
> | `side` | string | Yes | Values: `["control", "variant"]`. |
> | `ref` | string | Yes | |
> | `objective` | string | Yes | |
> | `metric` | string | Yes | |
> | `audience` | string | Yes | |
> | `source` | string | Yes | |
> | `provider` | string | Yes | |
> | `window` | object | Yes | |
> | `attribution` | string | Yes | |
> | `sampleSize` | number | Yes | |
> | `spend` | number | Yes | |
> | `events` | number | Yes | |
> | `numerator` | number | Yes | |
> | `denominator` | number | Yes | |
> | `freshnessAt` | string | Yes | |
> | `idempotencyKey` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **record-result-interpretation**
>
> `POST /api/mcp/record-result-interpretation`
>
> Attach a written interpretation to an experiment's results, optionally naming the hypothesis.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `experiment_id` | string | Yes | |
> | `text` | string | Yes | |
> | `hypothesis` | string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **reject-generation-artifact**
>
> `POST /api/mcp/reject-generation-artifact`
>
> Record a reviewer's rejection of one generated artifact by artifact\_id, with an optional reason.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `artifact_id` | string | Yes | |
> | `reason` | string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **resume-generation**
>
> `POST /api/mcp/resume-generation`
>
> Resume an interrupted generation run by its original idempotency\_key.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `idempotency_key` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **review-learning-memory**
>
> `POST /api/mcp/review-learning-memory`
>
> Approve or reject a proposed learning memory.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `candidateId` | string | Yes | |
> | `decision` | string | Yes | Values: `["approved", "rejected"]`. |
> | `reason` | string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **revoke-creative-brief**
>
> `POST /api/mcp/revoke-creative-brief`
>
> Withdraw approval from a creative brief version, with an optional reason.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `version_id` | string | Yes | |
> | `reason` | string | No | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

## Competitor monitoring

> **capture-competitor-snapshot**
>
> `POST /api/mcp/capture-competitor-snapshot`
>
> Search the public Meta Ad Library by page id or search terms in one market and save what it returns as a competitor snapshot.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `source_kind` | string | Yes | Values: `["page_id", "search_terms"]`. |
> | `query` | string | Yes | |
> | `market` | string | Yes | |
> | `ad_type` | string | No | Values: `["ALL", "POLITICAL_AND_ISSUE_ADS"]`. |
> | `limit` | integer | No | Minimum: `1`. |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **create-competitor-change-routine**
>
> `POST /api/mcp/create-competitor-change-routine`
>
> Create a scoped competitor change routine.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `source_id` | string | Yes | |
> | `name` | string | Yes | |
> | `cadence_seconds` | integer | Yes | Minimum: `1`. |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **dismiss-competitor-change-alert**
>
> `POST /api/mcp/dismiss-competitor-change-alert`
>
> Dismiss or restore a competitor change alert.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `alert_id` | string | Yes | |
> | `action` | string | Yes | Values: `["dismiss", "restore"]`. |
> | `idempotency_key` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **find-novelty-candidates**
>
> `POST /api/mcp/find-novelty-candidates`
>
> Compare recent competitor observations against this account's own creative history and return the concepts that are new rather than similar or duplicate, with citations.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `snapshot_id` | string | No | |
> | `limit` | integer | No | How many new concepts to return, 1 to 3. Defaults to 3. Minimum: `1`. Maximum: `3`. |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **list-competitor-board**
>
> `POST /api/mcp/list-competitor-board`
>
> List the tracked competitor board: saved snapshots and change alerts, with filters and cursor paging.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `filters` | object | No | |
> | `cursor` | string | No | |
> | `limit` | integer | No | Minimum: `1`. |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **pause-competitor-change-routine**
>
> `POST /api/mcp/pause-competitor-change-routine`
>
> Pause a competitor monitoring routine by routine\_id.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `routine_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **refresh-competitor-change-routine**
>
> `POST /api/mcp/refresh-competitor-change-routine`
>
> Refresh a competitor routine and deduplicate alerts.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `routine_id` | string | Yes | |
> | `source_id` | string | Yes | |
> | `durable_run_id` | string | Yes | |
> | `idempotency_key` | string | Yes | |
> | `current_hash` | string | No | |
> | `coverage` | string | Yes | Values: `["complete", "partial", "unavailable", "failed", "stale"]`. |
> | `observed_at` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).

> **resume-competitor-change-routine**
>
> `POST /api/mcp/resume-competitor-change-routine`
>
> Resume a paused competitor monitoring routine by routine\_id, so it checks for changes on its cadence again.
>
> | Field | Type | Required | Meaning or constraint |
> | - | - | - | - |
> | `account_id` | string | No | Authenticated Meta account id. |
> | `client_workspace_id` | string | No | Workspace context input; cannot grant access to another workspace or impersonate its owner. |
> | `routine_id` | string | Yes | |
>
> Advertised response statuses: `200`, `400`, `401`, `403`, `404`, `429`, `503`. See [status meanings](/developers/requests#handle-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.