> ## 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

<AccordionGroup>
  <Accordion title="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."
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Calculators and skills

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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
    }
    ```
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Creative generation and publishing

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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 &lt;timestamp&gt;`. |
    | `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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Connected-source queries

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Briefs, generation, and experiments

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Competitor monitoring

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>


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