REST endpoint reference - AutoAdy Help Center

Every endpoint below is a POST under https://www.autoady.io/api/mcp/ with Bearer authentication. Expand a tool to inspect its inputs. Required fields and nested-field requirements come from the published OpenAPI 3.1 schema; its JSON document also contains full response definitions. Plan, role, account, and credit gates still apply at execution. Use requests and responses 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:

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

An authentication or request-limit error can be bare:

{ "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-accountsList reachable ad accountsNo input fields. Send {}.Example JSON body:

{}

Advertised response statuses: 200, 400, 401, 429, 503. See status meanings.Success data schema:

{
  "type": "object",
  "required": [
    "accounts"
  ],
  "properties": {
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Accounts reachable by this key."
    }
  }
}

results

POST /api/mcp/resultsLive 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:

{
  "account_id": "act_1234567890",
  "level": "campaign",
  "date_preset": "last_7d"
}

Advertised response statuses: 200, 400, 401, 403, 404, 429, 503. See status meanings.

health

POST /api/mcp/healthAccount 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:

{
  "account_id": "act_1234567890"
}

Advertised response statuses: 200, 400, 401, 403, 404, 429, 503. See status meanings.

winner-insights

POST /api/mcp/winner-insightsWhat 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:

{
  "account_id": "act_1234567890"
}

Advertised response statuses: 200, 400, 401, 403, 404, 429, 503. See status meanings.

fatigue-alerts

POST /api/mcp/fatigue-alertsCreative 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:

{
  "account_id": "act_1234567890",
  "quick": true
}

Advertised response statuses: 200, 400, 401, 403, 404, 429, 503. See status meanings.

Calculators and skills

benchmarks

POST /api/mcp/benchmarksIndustry 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:

{
  "niche": "ecommerce"
}

Advertised response statuses: 200, 400, 401, 429, 503. See status meanings.

compare

POST /api/mcp/compareCompare 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:

{
  "niche": "ecommerce",
  "your_cpm": 12.4,
  "your_ctr": 1.8
}

Advertised response statuses: 200, 400, 401, 429, 503. See status meanings.

fatigue

POST /api/mcp/fatigueScore 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:

{
  "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.

list-skills

POST /api/mcp/list-skillsList the published media-buying skillsNo input fields. Send {}.Example JSON body:

{}

Advertised response statuses: 200, 400, 401, 429, 503. See status meanings.Success data schema:

{
  "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-skillRead one skill in full

Field	Type	Required	Meaning or constraint
`slug`	string	Yes	Skill slug, as returned by `list-skills`.

Example JSON body:

{
  "slug": "audit"
}

Advertised response statuses: 200, 400, 401, 429, 503. See status meanings.

Creative generation and publishing

ad-copy

POST /api/mcp/ad-copyGenerate Meta ad copySupply 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:

{
  "anyOf": [
    {
      "required": [
        "url"
      ]
    },
    {
      "required": [
        "description"
      ]
    }
  ]
}

Example JSON body:

{
  "url": "https://example.com/product",
  "objective": "Purchases",
  "tone": "Bold"
}

Advertised response statuses: 200, 400, 401, 403, 422, 429, 502, 503. See status meanings.

hooks

POST /api/mcp/hooksGenerate scroll-stopping hooksSupply 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:

{
  "anyOf": [
    {
      "required": [
        "url"
      ]
    },
    {
      "required": [
        "description"
      ]
    }
  ]
}

Example JSON body:

{
  "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.

save-creative

POST /api/mcp/save-creativeSave images to the creative librarySaves 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:

{
  "anyOf": [
    {
      "required": [
        "image_urls"
      ]
    },
    {
      "required": [
        "image_url"
      ]
    }
  ]
}

Example JSON body:

{
  "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.

push-creative

POST /api/mcp/push-creativeCreate an ad in an existing ad setSupply 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:

{
  "anyOf": [
    {
      "required": [
        "image_url"
      ]
    },
    {
      "required": [
        "video_url"
      ]
    }
  ]
}

Example JSON body (creates provider entities):

{
  "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.

creative-dna

POST /api/mcp/creative-dnaExtract 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:

{
  "account_id": "act_1234567890",
  "brand_url": "example.com"
}

Advertised response statuses: 200, 207, 400, 401, 403, 404, 409, 429, 503. See status meanings.

analyze-winning-ad

POST /api/mcp/analyze-winning-adBreak 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:

{
  "account_id": "act_1234567890",
  "ad_id": "23851234567890123"
}

Advertised response statuses: 200, 400, 401, 403, 404, 429, 503. See status meanings.

url-to-ads

POST /api/mcp/url-to-adsTurn 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:

{
  "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.

multiply-winner

POST /api/mcp/multiply-winnerGenerate 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:

{
  "anyOf": [
    {
      "required": [
        "ad_id"
      ]
    },
    {
      "required": [
        "image_url"
      ]
    }
  ]
}

Example JSON body:

{
  "account_id": "act_1234567890",
  "ad_id": "23851234567890123",
  "count": 6
}

Advertised response statuses: 200, 207, 400, 401, 403, 404, 409, 429, 503. See status meanings.

competitor-creatives

POST /api/mcp/competitor-creativesGenerate 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:

{
  "anyOf": [
    {
      "required": [
        "competitor_name"
      ]
    },
    {
      "required": [
        "page_id"
      ]
    }
  ]
}

Example JSON body:

{
  "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.

creative-matrix

POST /api/mcp/creative-matrixGenerate 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:

{
  "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.

creative-loop

POST /api/mcp/creative-loopConfigure 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:

{
  "account_id": "act_1234567890",
  "auto_launch": false
}

Advertised response statuses: 200, 207, 400, 401, 403, 404, 409, 429, 503. See status meanings.

Connected-source queries

integrations-get-status

POST /api/mcp/integrations-get-statusRead 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.

integrations-intelligence-report

POST /api/mcp/integrations-intelligence-reportBuild 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.

integrations-list-connections

POST /api/mcp/integrations-list-connectionsList 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.

integrations-query

POST /api/mcp/integrations-queryRun 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.

Briefs, generation, and experiments

approve-creative-brief

POST /api/mcp/approve-creative-briefApprove 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.

approve-generation-artifact

POST /api/mcp/approve-generation-artifactRecord 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.

approve-meta-test-plan

POST /api/mcp/approve-meta-test-planApprove 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.

assess-experiment

POST /api/mcp/assess-experimentAssess 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.

create-creative-brief

POST /api/mcp/create-creative-briefCreate 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.

create-experiment

POST /api/mcp/create-experimentRegister 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.

edit-creative-brief

POST /api/mcp/edit-creative-briefChange 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.

generate-from-brief

POST /api/mcp/generate-from-briefGenerate 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.

get-creative-brief

POST /api/mcp/get-creative-briefRead 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.

generation-status

POST /api/mcp/generation-statusRead 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.

list-learning

POST /api/mcp/list-learningList 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.

preview-meta-test-plan

POST /api/mcp/preview-meta-test-planPreview 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.

propose-learning-memory

POST /api/mcp/propose-learning-memoryPropose 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.

record-experiment-result

POST /api/mcp/record-experiment-resultRecord 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.

record-result-interpretation

POST /api/mcp/record-result-interpretationAttach 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.

reject-generation-artifact

POST /api/mcp/reject-generation-artifactRecord 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.

resume-generation

POST /api/mcp/resume-generationResume 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.

review-learning-memory

POST /api/mcp/review-learning-memoryApprove 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.

revoke-creative-brief

POST /api/mcp/revoke-creative-briefWithdraw 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.

Competitor monitoring

capture-competitor-snapshot

POST /api/mcp/capture-competitor-snapshotSearch 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.

create-competitor-change-routine

POST /api/mcp/create-competitor-change-routineCreate 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.

dismiss-competitor-change-alert

POST /api/mcp/dismiss-competitor-change-alertDismiss 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.

find-novelty-candidates

POST /api/mcp/find-novelty-candidatesCompare 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.

list-competitor-board

POST /api/mcp/list-competitor-boardList 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.

pause-competitor-change-routine

POST /api/mcp/pause-competitor-change-routinePause 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.

refresh-competitor-change-routine

POST /api/mcp/refresh-competitor-change-routineRefresh 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.

resume-competitor-change-routine

POST /api/mcp/resume-competitor-change-routineResume 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.

​Response contracts

​Account reads

​Calculators and skills

​Creative generation and publishing

​Connected-source queries

​Briefs, generation, and experiments

​Competitor monitoring

Response contracts

Account reads

Calculators and skills

Creative generation and publishing

Connected-source queries

Briefs, generation, and experiments

Competitor monitoring