Developer documentation

Returns every Meta ad account this API key's workspace can act on, with id, name and currency. Call this first — the `account_id` values it returns are the only ones the other tools accept. The request body is ignored; send `{}`.

Live Meta delivery numbers for one account — spend, results, CPA/CPL, CTR, CPM — aggregated at the level you ask for. Figures come from the Meta Marketing API through AutoAdy's conversion-counting layer, so they match what the app shows.

Scores the account across delivery, efficiency, creative freshness and structure, and returns the component scores behind the headline number. Uses the active account when `account_id` is omitted.

Analyses the account's top performers and reports the patterns they share — formats, hooks, angles, and the creative traits that correlate with results. Uses the active account when `account_id` is omitted.

Flags ads whose frequency is climbing while CTR decays — the ones that need rotating before they burn budget. Uses the active account when `account_id` is omitted.

Returns AutoAdy's Meta ads benchmarks (CPM, CTR, CPA) for one industry, or for every industry when `niche` is omitted. Pure lookup — it touches no ad account and needs no Meta connection. Note: an unrecognised `niche` still answers **HTTP 200**, with `data.error` naming the available niches. Check `data.error` as well as the status.

Scores your CPM, CTR and/or CPL against the benchmark for a niche and says whether each is ahead or behind. Supply at least one of the three metrics. Pure calculation — no ad account is read. Note: a missing or unknown `niche`, or no metric at all, still answers **HTTP 200** with `data.error`.

Given a frequency, a CTR trend and a run length, returns a fatigue verdict and what to do about it. Pure calculation on the numbers you pass — use `fatigue-alerts` instead if you want AutoAdy to pull the numbers from a live account. Note: validation failures answer **HTTP 200** with `data.error`.

Returns every published AutoAdy skill with its slug, title and summary — the methodology the AI itself runs on. Use the slugs with `get-skill`. The request body is ignored; send `{}`.

Returns the complete text of one published skill — the thresholds, decision rules and worked reasoning behind it. The `slug` is trimmed and lowercased before lookup. Note: a missing or unknown `slug` still answers **HTTP 200**, with `data.error` naming the valid slugs. Check `data.error` as well as the status.

Writes primary text, headlines and descriptions for a Meta ad. Give it either a `url` to read the offer from, or a `description` you write yourself — at least one is required.

Produces opening lines and hook concepts for video or static ads. Give it either a `url` or a `description` — at least one is required.

Stores externally generated images in the AutoAdy creative library so they can be pushed to an ad set later. Supply `image_urls` (up to 10) or a single `image_url`. URLs must be public `http`/`https`. Loopback, link-local and private-range hosts are rejected.

Uploads an image or video to Meta, builds the creative, and creates an ad inside an existing ad set. This is a real write against the ad account. Requirements: exactly one of `image_url` / `video_url`, and exactly one destination (`website_url` or `lead_gen_form_id`). Media URLs must be public `http`/`https`; private and loopback hosts are rejected. `request_id` is a caller-chosen idempotency key — reusing one returns the original outcome instead of creating a second ad. Ads are created **PAUSED** unless `status` is `"ACTIVE"`, and going straight to ACTIVE additionally requires `hard_confirm_text`. Writes are metered per ad account (200 per hour) on top of the per-key request limit.

Reads a brand's site and derives its voice, palette, claims and visual signature, then stores that profile so later creative generation stays on-brand. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Deconstructs a single high-performing ad — hook, angle, visual structure, offer framing — into a reusable brief you can build variations from. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`.

Scrapes a product or landing page and generates a batch of ad creatives across several angles. Generated images consume the account's image quota. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Takes one proven creative — by `ad_id` or by direct `image_url` — and produces variations that keep what works and change what is worth testing. Generated images consume the account's image quota. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Pulls a competitor's live ads from the public Meta Ad Library, reads what they are running, and generates on-brand creatives that answer it. Identify the competitor by name or by Meta page id. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Generates the cross-product of the angles, hooks and visual styles you pass, so a single call produces a structured test grid rather than a loose batch. The grid is capped: `angles.length × hooks.length × visual_styles.length` must not exceed **27**, or the call is rejected with 400. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Finds fatiguing ads, generates replacements from what is winning, and stages them in the account. New creatives are created **PAUSED** unless `auto_launch` is `true`. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.

Finds ads spending well above the account's average cost per result and pauses them. This is a real write, so it takes an idempotency key and is metered by the per-account write budget (200 writes per hour). A partially applied run answers **207**. Runs directly against the account this API key can reach — the same execution path as the MCP server. **404** means no reachable Meta ad account (none connected, or the `account_id` you passed is not one this workspace can act on); **403** means the plan does not cover the tool or the key belongs to a read-only Client Viewer; **400** carries a tool-level failure under `data.error`. This workflow writes to the ad account, so it is metered by the per-account write budget and is idempotent on the request body: retrying an identical body replays the first run's result instead of writing twice. To force a genuinely new run of the same input, pass a fresh `request_id`. A run the write boundary refused answers **409**.