ADSMCP REST API for Ads Automation

The ADSMCP REST API exposes every tool the MCP server does, over plain HTTP. Use it from any client that can’t speak SSE — n8n, Zapier, Make, GitHub Actions, Python scripts, cron jobs, or your own backend.

Get your API key Generate a key at adsmcp.ai/keys, then call any of the endpoints below with a bearer token. Free tier includes 15 calls — enough to test everything.


Base URL	`https://api.adsmcp.si`
Interactive sandbox	api.adsmcp.ai/docs (Swagger UI)
Raw OpenAPI spec	api.adsmcp.ai/openapi.json

Use cases

Real patterns teams ship on the REST API today. Each one is just a few HTTP calls — the hard part is already done for you.

Slack ChatOps for campaigns Team member posts a campaign brief in #campaign-activation → n8n parses it → REST API creates the campaign PAUSED → bot confirms in the thread. Nobody needs a Meta / Google login.

Daily account briefings Every morning, pull CPL / ROAS / spend for each account manager’s book of business and deliver a Slack digest. Alert states (🟢 on-track, 🟡 watch, 🔴 red) computed against targets you store in a Google Sheet.

Portfolio rollups for owners Weekly health summary across every client account — who’s over/under target, budget utilization, top / bottom 5 performers, per-manager breakdown.

Alert thresholds & auto-pause Watch CPL vs target, flag breaches, pause underperforming ad sets on a rule. create_monitor handles the poll loop on our side so you don’t run a cron.

SaaS product embedding Your app creates a starter campaign for every new customer during onboarding. Idempotency-Key makes signup retries safe even under network flakiness.

Headless CI / scheduled ops Launch seasonal campaigns from GitHub Actions, kick off end-of-month reports from cron, trigger pause / resume on holiday calendars. No browser, no OAuth dance — just an API key.

How they wire up

Each pattern is a small variation on the same two primitives: read-only tools for data, write tools for changes.

Pattern	Ingress	ADSMCP calls	Egress
Slack ChatOps	Slack webhook → n8n	`create_meta_image_campaign`, `add_meta_ad_set`, `add_meta_ad`	Slack thread reply
Daily briefings	Cron (n8n / Zapier / cron)	`get_campaign_performance`, `analyze_wasted_spend`	Slack DM per manager
Portfolio rollups	Cron, weekly	`get_campaign_performance` across accounts	Email / Notion / Slack
Auto-pause guardrail	`create_monitor` (ADSMCP-hosted)	`pause_campaign` or `update_campaign` (lower the daily budget) on breach	Slack alert + action log
SaaS onboarding	Your app’s signup hook	`create_search_campaign` with `Idempotency-Key`	Campaign ID stored in your DB
Scheduled ops	GitHub Actions / cron	Whatever the job needs	Job log + Slack status

[!TIP] Agency pattern: pass ad_account_id, customer_id, or advertiser_id on every call to route to the right client account. One API key can manage hundreds of connected accounts from a single backend.

Why use the REST API?

You’re already using ChatGPT, Claude, or Cursor with ADSMCP’s MCP server — and that’s great for interactive work. But there are jobs an AI conversation can’t do:

Your agent shuts off when you close the tab. A cron that pulls daily performance at 9am needs to run without a human watching.
No-code automation tools don’t speak MCP. n8n, Zapier, and Make only know HTTP. MCP uses SSE.
Your backend wants to embed campaign creation. A SaaS onboarding flow that creates a starter campaign for every new customer can’t open a chat with Claude.
Multi-step workflows need to be deterministic. “If CTR drops below 2%, pause the campaign” belongs in code, not a prompt.

The REST API gives you the same tools, over plain HTTP that every automation platform understands.

How it relates to MCP

Same backend. Same auth. Same quota. Same write-guards. Only the transport differs. One logical endpoint per tool: POST /api/v1/tools/<tool_name>/execute. Call add_meta_ad from a chat via MCP or from a cron via REST — the result, the quota cost, and the log entry are identical.

Quickstart

curl

curl https://api.adsmcp.si/api/v1/tools/list_connected_accounts/execute \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"arguments": {}}'

Python

import requests

r = requests.post(
    "https://api.adsmcp.si/api/v1/tools/list_connected_accounts/execute",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"arguments": {}},
)
r.raise_for_status()
print(r.json()["data"])

Node (fetch)

const res = await fetch(
  "https://api.adsmcp.si/api/v1/tools/list_connected_accounts/execute",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ arguments: {} }),
  },
);
const { data } = await res.json();
console.log(data);

n8n Use the HTTP Request node:

Field	Value
Method	`POST`
URL	`https://api.adsmcp.si/api/v1/tools/<tool_name>/execute`
Authentication	`Header Auth` → name `Authorization`, value `Bearer sk_live_...`
Body Content Type	`JSON`
Body	`{ "arguments": { ... } }`

Add an Idempotency-Key header (UUID) on write operations so retries collapse into one call.

Core concepts

Authentication

Every call requires an API key generated at adsmcp.ai/keys. Pass it as a bearer token — keys are prefixed sk_live_. Treat them as secrets; never commit them. Keys provide the same access as OAuth tokens used by MCP clients — same tools, same quotas.

Request envelope

Every endpoint takes a POST with tool-specific input wrapped in an arguments object:

{
  "arguments": {
    "ad_set_id": "120203456789",
    "headline": "Spring sale",
    "primary_text": "Up to 40% off"
  }
}

Response envelope

Success:

{
  "success": true,
  "tool": "add_meta_ad",
  "data": {
    "ad_id": "120203456789",
    "quota": { "used": 42, "limit": 150, "tier": "plus", "period_end": "2026-05-01" }
  }
}

Error:

{
  "success": false,
  "is_error": true,
  "error": "ad_set_id is required"
}

Quota & billing

Every successful billable call decrements your monthly tool-call allowance. The current counter is attached to every 200 response under data.quota. When the limit is hit, the API returns HTTP 402 with a quota block including upgrade_url. Read-only diagnostic tools never consume quota: get_usage_status, list_connected_accounts, get_connections_status. See Pricing for tier limits.

Idempotency

Write operations accept an Idempotency-Key header. A repeated call with the same key returns the cached result rather than executing twice.

curl https://api.adsmcp.si/api/v1/tools/add_meta_ad/execute \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 4a1c2d3e-..." \
  -H "Content-Type: application/json" \
  -d '{"arguments": {...}}'

[!TIP] Strongly recommended for n8n, Zapier, and any retry-prone client. Generate a fresh UUID per logical operation — not per retry — so retries collapse into one write.

Multi-account users

If you’ve connected multiple accounts on the same platform (e.g. an agency with 10 Meta ad accounts), specify the account on every call:

ad_account_id — Meta Ads
customer_id — Google Ads
advertiser_id — TikTok Ads, LinkedIn Ads
account_id — generic fallback

Omitting the field returns HTTP 400 with a list of valid IDs. Use list_connected_accounts to discover them.

HTTP status codes

Status	Meaning
`200`	Success. Parse `data`.
`400`	Tool-level error. Surface `error` to users. Includes multi-account prompts and validation failures.
`401`	Invalid or missing API key.
`402`	ADSMCP quota exhausted. Response includes `upgrade_url`.
`404`	Unknown `tool_name` in the URL.
`409`	Idempotency key reused with different arguments.
`429`	Upstream ad platform rate-limited us (Meta / Google / etc.). Retry with backoff.
`500`	Unexpected server error. Report to support.

No streaming

This endpoint is plain request/response JSON. No SSE, no chunked streaming. Safe to use from n8n Cloud, Zapier, Make, curl, Python requests, Node fetch, Go net/http, and every mainstream HTTP library.

Tool coverage

Google Ads 51 tools — campaigns, ad groups, keywords, extensions, Performance Max, Demand Gen

Meta Ads 36 tools — image, video, carousel, DCO, audiences, placements

LinkedIn Ads 45 tools — campaigns, creatives, audiences, conversion tracking

TikTok Ads 29 tools — campaigns, ad groups, ads, geo, optimization events

Monitoring & Reporting 13 tools — cross-platform performance, wasted spend, search terms

Account Management 3 tools — list connected accounts, connection status, usage

[!NOTE] The endpoint reference above is being expanded to the full 400+ tool surface. Amazon Ads (61 tools) and ChatGPT Ads (50 tools), plus the newest Google Shopping/App, Meta Advantage+ Catalog, and LinkedIn tools, are all available over the same REST transport today — every MCP tool has a matching POST /api/v1/tools/{tool_name}/execute endpoint. See the Tool Catalog for the complete, current list while the interactive reference pages are regenerated.

Architecture patterns

Slack ChatOps — campaign creation from a message

Every campaign is created PAUSED — the requester reviews and activates manually. The Idempotency-Key header means a retry from n8n never creates a duplicate campaign.

Daily briefings — scheduled read-only reports

Read-only tools (get_*, list_*, analyze_*) don’t consume quota. At ~3 calls per account per briefing, 100 accounts = 300 calls / morning.

Guarded auto-pause — ADSMCP-hosted monitor

You don’t run the cron — ADSMCP does. Use this when you want rules to fire without babysitting an n8n workflow.

SaaS onboarding — embedded create

# New customer signs up → create a starter Search campaign
import uuid, requests

resp = requests.post(
    "https://api.adsmcp.si/api/v1/tools/create_search_campaign/execute",
    headers={
        "Authorization": f"Bearer {os.environ['ADSMCP_KEY']}",
        "Idempotency-Key": f"signup-{customer.id}",  # stable per customer
    },
    json={"arguments": {
        "customer_id": customer.google_ads_customer_id,
        "campaign_name": f"{customer.brand} — starter",
        "budget_daily": 20,
        "keywords": customer.seed_keywords,
    }},
    timeout=60,
)
resp.raise_for_status()
customer.starter_campaign_id = resp.json()["data"]["campaign_id"]

Reusing signup-{customer.id} as the key means signup retries never double-create.

What’s excluded from REST

These exist in MCP but are intentionally omitted from the REST surface — call the underlying tools directly instead:

Unified aggregators (ads_query, ads_optimize, ads_create, ads_manage, account_info) — LLM-convenience wrappers that dispatch to real tools.
Federated router meta-tools (google_ads, meta_ads, linkedin_ads, tiktok_ads, monitoring_and_reporting) — MCP-transport workaround for Claude Desktop’s tool-list size limit. Irrelevant for REST.

FAQ

Do REST and MCP share the same quota? Yes. Both transports decrement the same monthly allowance on your ADSMCP plan. A call made from ChatGPT (MCP) and a call made from a curl script (REST) count the same.

Can I use the REST API from a browser? Technically yes, but don’t. An API key in browser JavaScript is visible to anyone who opens DevTools. Call the REST API from your backend, or use the MCP server for user-facing AI experiences.

How do I handle rate limiting from Meta / Google / etc.? If an upstream ad platform rate-limits us, you’ll see HTTP 429. Back off and retry — typically 30–60 seconds is enough. ADSMCP’s internal rate limits (HTTP 402 for quota) are separate from upstream limits.

Is there a webhook or subscription API? Not yet. For “run every X hours” style jobs, use create_monitor — it polls on our side and emits alerts you can wire into Slack or email. For true push-based webhooks, book a call.

Can I use the same API key from multiple machines? Yes. Keys aren’t pinned to a device. Just be aware that concurrent calls share one quota — if you parallelize heavily, you may hit HTTP 402 sooner.

What happens if my key leaks? Revoke it immediately at adsmcp.ai/keys and generate a new one. Revoked keys stop working within seconds.

How MCP Works — the protocol the REST API mirrors
Core Workflows — step-by-step tool sequences for common jobs
Tool Catalog — the full 400+ tool reference
Pricing — quota tiers and overage billing
Security — how API keys, OAuth, and session data are handled

Overview

General

Google Ads

Meta Ads

LinkedIn Ads

TikTok Ads

Audit

Monitoring

HTTP API

ADSMCP REST API for Ads Automation

Use cases

How they wire up

Why use the REST API?

How it relates to MCP

Quickstart

Core concepts

Authentication

Request envelope

Response envelope

Quota & billing

Idempotency

Multi-account users

HTTP status codes

No streaming

Tool coverage

Architecture patterns

Slack ChatOps — campaign creation from a message

Daily briefings — scheduled read-only reports

Guarded auto-pause — ADSMCP-hosted monitor

SaaS onboarding — embedded create

What’s excluded from REST

FAQ

​Use cases

​How they wire up

​Why use the REST API?

​How it relates to MCP

​Quickstart

​Core concepts

​Authentication

​Request envelope

​Response envelope

​Quota & billing

​Idempotency

​Multi-account users

​HTTP status codes

​No streaming

​Tool coverage

​Architecture patterns

​Slack ChatOps — campaign creation from a message

​Daily briefings — scheduled read-only reports

​Guarded auto-pause — ADSMCP-hosted monitor

​SaaS onboarding — embedded create

​What’s excluded from REST

​FAQ

​Related

Use cases

How they wire up

Why use the REST API?

How it relates to MCP

Quickstart

Core concepts

Authentication

Request envelope

Response envelope

Quota & billing

Idempotency

Multi-account users

HTTP status codes

No streaming

Tool coverage

Architecture patterns

Slack ChatOps — campaign creation from a message

Daily briefings — scheduled read-only reports

Guarded auto-pause — ADSMCP-hosted monitor

SaaS onboarding — embedded create

What’s excluded from REST

FAQ

Related